-
-
-
{
+ return this.$store.reduce({
+ name: "code",
+ stream,
+ reducer: this.#reducer,
+ });
+ }
+
+ get isClaimed(): boolean {
+ return this.claimedAt !== undefined;
+ }
+
+ // -------------------------------------------------------------------------
+ // Folder
+ // -------------------------------------------------------------------------
+
+ with(event: EventStoreFactory["$events"][number]["$record"]): void {
+ switch (event.type) {
+ case "code:created": {
+ this.id = event.stream;
+ this.value = event.data.value;
+ this.identity = event.data.identity;
+ this.createdAt = getDate(event.created);
+ break;
+ }
+ case "code:claimed": {
+ this.claimedAt = getDate(event.created);
+ break;
+ }
+ }
+ }
+
+ // -------------------------------------------------------------------------
+ // Actions
+ // -------------------------------------------------------------------------
+
+ claim(): this {
+ return this.push({
+ type: "code:claimed",
+ stream: this.id,
+ });
+ }
+}
diff --git a/api/libraries/event-store/aggregates/mod.ts b/api/libraries/event-store/aggregates/mod.ts
new file mode 100644
index 0000000..fad22fc
--- /dev/null
+++ b/api/libraries/event-store/aggregates/mod.ts
@@ -0,0 +1,8 @@
+import { AggregateFactory } from "@valkyr/event-store";
+
+import { Account } from "./account.ts";
+import { Code } from "./code.ts";
+import { Organization } from "./organization.ts";
+import { Role } from "./role.ts";
+
+export const aggregates = new AggregateFactory([Account, Code, Organization, Role]);
diff --git a/api/libraries/event-store/aggregates/organization.ts b/api/libraries/event-store/aggregates/organization.ts
new file mode 100644
index 0000000..d561cff
--- /dev/null
+++ b/api/libraries/event-store/aggregates/organization.ts
@@ -0,0 +1,65 @@
+import { AggregateRoot, getDate, makeAggregateReducer } from "@valkyr/event-store";
+
+import { db } from "~libraries/read-store/mod.ts";
+
+import { Auditor } from "../events/auditor.ts";
+import { EventStoreFactory } from "../events/mod.ts";
+import { projector } from "../projector.ts";
+
+export class Organization extends AggregateRoot {
+ static override readonly name = "organization";
+
+ id!: string;
+
+ name!: string;
+
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ // -------------------------------------------------------------------------
+ // Factories
+ // -------------------------------------------------------------------------
+
+ static #reducer = makeAggregateReducer(Organization);
+
+ static create(name: string, meta: Auditor): Organization {
+ return new Organization().push({
+ type: "organization:created",
+ data: { name },
+ meta,
+ });
+ }
+
+ static async getById(stream: string): Promise {
+ return this.$store.reduce({ name: "organization", stream, reducer: this.#reducer });
+ }
+
+ // -------------------------------------------------------------------------
+ // Reducer
+ // -------------------------------------------------------------------------
+
+ with(event: EventStoreFactory["$events"][number]["$record"]): void {
+ switch (event.type) {
+ case "organization:created": {
+ this.id = event.stream;
+ this.name = event.data.name;
+ this.createdAt = getDate(event.created);
+ break;
+ }
+ }
+ }
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Projectors
+ |--------------------------------------------------------------------------------
+ */
+
+projector.on("organization:created", async ({ stream: id, data: { name }, created }) => {
+ await db.collection("organizations").insertOne({
+ id,
+ name,
+ createdAt: getDate(created),
+ });
+});
diff --git a/api/libraries/event-store/aggregates/role.ts b/api/libraries/event-store/aggregates/role.ts
new file mode 100644
index 0000000..768c209
--- /dev/null
+++ b/api/libraries/event-store/aggregates/role.ts
@@ -0,0 +1,118 @@
+import { AggregateRoot, getDate, makeAggregateReducer } from "@valkyr/event-store";
+
+import { db } from "~libraries/read-store/database.ts";
+
+import type { Auditor } from "../events/auditor.ts";
+import { EventStoreFactory } from "../events/mod.ts";
+import type { RoleCreatedData, RolePermissionOperation } from "../events/role.ts";
+import { projector } from "../projector.ts";
+
+export class Role extends AggregateRoot {
+ static override readonly name = "role";
+
+ id!: string;
+
+ name!: string;
+ permissions: { [resource: string]: Set } = {};
+
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ // -------------------------------------------------------------------------
+ // Factories
+ // -------------------------------------------------------------------------
+
+ static #reducer = makeAggregateReducer(Role);
+
+ static create(data: RoleCreatedData, meta: Auditor): Role {
+ return new Role().push({
+ type: "role:created",
+ data,
+ meta,
+ });
+ }
+
+ static async getById(stream: string): Promise {
+ return this.$store.reduce({ name: "role", stream, reducer: this.#reducer });
+ }
+
+ // -------------------------------------------------------------------------
+ // Reducer
+ // -------------------------------------------------------------------------
+
+ override with(event: EventStoreFactory["$events"][number]["$record"]): void {
+ switch (event.type) {
+ case "role:created": {
+ this.id = event.stream;
+ this.createdAt = getDate(event.created);
+ this.updatedAt = getDate(event.created);
+ break;
+ }
+ case "role:name-set": {
+ this.name = event.data;
+ this.updatedAt = getDate(event.created);
+ break;
+ }
+ case "role:permissions-set": {
+ for (const operation of event.data) {
+ if (operation.type === "grant") {
+ if (this.permissions[operation.resource] === undefined) {
+ this.permissions[operation.resource] = new Set();
+ }
+ this.permissions[operation.resource].add(operation.action);
+ }
+ if (operation.type === "deny") {
+ if (operation.action === undefined) {
+ delete this.permissions[operation.resource];
+ } else {
+ this.permissions[operation.resource]?.delete(operation.action);
+ }
+ }
+ }
+ break;
+ }
+ }
+ }
+
+ // -------------------------------------------------------------------------
+ // Actions
+ // -------------------------------------------------------------------------
+
+ setName(name: string, meta: Auditor): this {
+ return this.push({
+ type: "role:name-set",
+ stream: this.id,
+ data: name,
+ meta,
+ });
+ }
+
+ setPermissions(operations: RolePermissionOperation[], meta: Auditor): this {
+ return this.push({
+ type: "role:permissions-set",
+ stream: this.id,
+ data: operations,
+ meta,
+ });
+ }
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Projectors
+ |--------------------------------------------------------------------------------
+ */
+
+projector.on("role:created", async ({ stream, data: { name, permissions } }) => {
+ await db.collection("roles").insertOne({
+ id: stream,
+ name,
+ permissions: permissions.reduce(
+ (map, permission) => {
+ map[permission.resource] = permission.actions;
+ return map;
+ },
+ {} as Record,
+ ),
+ });
+});
diff --git a/api/libraries/event-store/event-store.ts b/api/libraries/event-store/event-store.ts
new file mode 100644
index 0000000..5c5a315
--- /dev/null
+++ b/api/libraries/event-store/event-store.ts
@@ -0,0 +1,25 @@
+import { EventStore } from "@valkyr/event-store";
+import { MongoAdapter } from "@valkyr/event-store/mongo";
+
+import { container } from "~libraries/database/container.ts";
+
+import { aggregates } from "./aggregates/mod.ts";
+import { events } from "./events/mod.ts";
+import { projector } from "./projector.ts";
+
+export const eventStore = new EventStore({
+ adapter: new MongoAdapter(() => container.get("client"), "balto:event-store"),
+ events,
+ aggregates,
+ snapshot: "auto",
+});
+
+eventStore.onEventsInserted(async (records, { batch }) => {
+ if (batch !== undefined) {
+ await projector.pushMany(batch, records);
+ } else {
+ for (const record of records) {
+ await projector.push(record, { hydrated: false, outdated: false });
+ }
+ }
+});
diff --git a/api/libraries/event-store/events/account.ts b/api/libraries/event-store/events/account.ts
new file mode 100644
index 0000000..ff00930
--- /dev/null
+++ b/api/libraries/event-store/events/account.ts
@@ -0,0 +1,29 @@
+import { event } from "@valkyr/event-store";
+import { email, name, phone } from "relay/schemas";
+import z from "zod";
+
+import { auditor } from "./auditor.ts";
+
+const created = z.discriminatedUnion([
+ z.object({
+ type: z.literal("admin"),
+ }),
+ z.object({
+ type: z.literal("consultant"),
+ }),
+ z.object({
+ type: z.literal("organization"),
+ organizationId: z.string(),
+ }),
+]);
+
+export default [
+ event.type("account:created").data(created).meta(auditor),
+ event.type("account:avatar:added").data(z.string()).meta(auditor),
+ event.type("account:name:added").data(name).meta(auditor),
+ event.type("account:email:added").data(email).meta(auditor),
+ event.type("account:phone:added").data(phone).meta(auditor),
+ event.type("account:role:added").data(z.string()).meta(auditor),
+];
+
+export type AccountCreatedData = z.infer;
diff --git a/api/libraries/event-store/events/auditor.ts b/api/libraries/event-store/events/auditor.ts
new file mode 100644
index 0000000..9819416
--- /dev/null
+++ b/api/libraries/event-store/events/auditor.ts
@@ -0,0 +1,7 @@
+import z from "zod";
+
+export const auditor = z.object({
+ accountId: z.string(),
+});
+
+export type Auditor = z.infer;
diff --git a/api/libraries/event-store/events/code.ts b/api/libraries/event-store/events/code.ts
new file mode 100644
index 0000000..cdca4d7
--- /dev/null
+++ b/api/libraries/event-store/events/code.ts
@@ -0,0 +1,30 @@
+import { event } from "@valkyr/event-store";
+import z from "zod";
+
+const identity = z.discriminatedUnion([
+ z.object({
+ type: z.literal("admin"),
+ accountId: z.string(),
+ }),
+ z.object({
+ type: z.literal("consultant"),
+ accountId: z.string(),
+ }),
+ z.object({
+ type: z.literal("organization"),
+ organizationId: z.string(),
+ accountId: z.string(),
+ }),
+]);
+
+export default [
+ event.type("code:created").data(
+ z.object({
+ value: z.string(),
+ identity,
+ }),
+ ),
+ event.type("code:claimed"),
+];
+
+export type CodeIdentity = z.infer;
diff --git a/api/libraries/event-store/events/mod.ts b/api/libraries/event-store/events/mod.ts
new file mode 100644
index 0000000..3c5f0dc
--- /dev/null
+++ b/api/libraries/event-store/events/mod.ts
@@ -0,0 +1,11 @@
+import { EventFactory } from "@valkyr/event-store";
+
+import account from "./account.ts";
+import code from "./code.ts";
+import organization from "./organization.ts";
+import role from "./role.ts";
+import strategy from "./strategy.ts";
+
+export const events = new EventFactory([...account, ...code, ...organization, ...role, ...strategy]);
+
+export type EventStoreFactory = typeof events;
diff --git a/api/libraries/event-store/events/organization.ts b/api/libraries/event-store/events/organization.ts
new file mode 100644
index 0000000..cea6003
--- /dev/null
+++ b/api/libraries/event-store/events/organization.ts
@@ -0,0 +1,11 @@
+import { event } from "@valkyr/event-store";
+import z from "zod";
+
+import { auditor } from "./auditor.ts";
+
+export default [
+ event
+ .type("organization:created")
+ .data(z.object({ name: z.string() }))
+ .meta(auditor),
+];
diff --git a/api/libraries/event-store/events/role.ts b/api/libraries/event-store/events/role.ts
new file mode 100644
index 0000000..6635512
--- /dev/null
+++ b/api/libraries/event-store/events/role.ts
@@ -0,0 +1,37 @@
+import { event } from "@valkyr/event-store";
+import z from "zod";
+
+import { auditor } from "./auditor.ts";
+
+const created = z.object({
+ name: z.string(),
+ permissions: z.array(
+ z.object({
+ resource: z.string(),
+ actions: z.array(z.string()),
+ }),
+ ),
+});
+
+const operation = z.discriminatedUnion([
+ z.object({
+ type: z.literal("grant"),
+ resource: z.string(),
+ action: z.string(),
+ }),
+ z.object({
+ type: z.literal("deny"),
+ resource: z.string(),
+ action: z.string().optional(),
+ }),
+]);
+
+export default [
+ event.type("role:created").data(created).meta(auditor),
+ event.type("role:name-set").data(z.string()).meta(auditor),
+ event.type("role:permissions-set").data(z.array(operation)).meta(auditor),
+];
+
+export type RoleCreatedData = z.infer;
+
+export type RolePermissionOperation = z.infer;
diff --git a/api/libraries/event-store/events/strategy.ts b/api/libraries/event-store/events/strategy.ts
new file mode 100644
index 0000000..b21d12e
--- /dev/null
+++ b/api/libraries/event-store/events/strategy.ts
@@ -0,0 +1,13 @@
+import { event } from "@valkyr/event-store";
+import z from "zod";
+
+import { auditor } from "./auditor.ts";
+
+export default [
+ event.type("strategy:email:added").data(z.string()).meta(auditor),
+ event.type("strategy:passkey:added").meta(auditor),
+ event
+ .type("strategy:password:added")
+ .data(z.object({ alias: z.string(), password: z.string() }))
+ .meta(auditor),
+];
diff --git a/api/libraries/event-store/mod.ts b/api/libraries/event-store/mod.ts
new file mode 100644
index 0000000..23cc215
--- /dev/null
+++ b/api/libraries/event-store/mod.ts
@@ -0,0 +1,2 @@
+export * from "./event-store.ts";
+export * from "./projector.ts";
diff --git a/api/libraries/event-store/projector.ts b/api/libraries/event-store/projector.ts
new file mode 100644
index 0000000..4a7e831
--- /dev/null
+++ b/api/libraries/event-store/projector.ts
@@ -0,0 +1,5 @@
+import { Projector } from "@valkyr/event-store";
+
+import { EventStoreFactory } from "./events/mod.ts";
+
+export const projector = new Projector();
diff --git a/api/libraries/logger/chalk.ts b/api/libraries/logger/chalk.ts
new file mode 100644
index 0000000..4a5d72d
--- /dev/null
+++ b/api/libraries/logger/chalk.ts
@@ -0,0 +1,48 @@
+import { HexValue } from "./color/hex.ts";
+import { type BGColor, type Color, hexToBgColor, hexToColor, type Modifier, styles } from "./color/styles.ts";
+
+export const chalk = {
+ color(hex: HexValue): (value: string) => string {
+ const color = hexToColor(hex);
+ return (value: string) => `${color}${value}${styles.modifier.reset}`;
+ },
+ bgColor(hex: HexValue): (value: string) => string {
+ const color = hexToBgColor(hex);
+ return (value: string) => `${color}${value}${styles.modifier.reset}`;
+ },
+} as Chalk;
+
+for (const key in styles.modifier) {
+ chalk[key as Modifier] = function (value: string) {
+ return toModifiedValue(key as Modifier, value);
+ };
+}
+
+for (const key in styles.color) {
+ chalk[key as Color] = function (value: string) {
+ return toColorValue(key as Color, value);
+ };
+}
+
+for (const key in styles.bgColor) {
+ chalk[key as BGColor] = function (value: string) {
+ return toBGColorValue(key as BGColor, value);
+ };
+}
+
+function toModifiedValue(key: Modifier, value: string): string {
+ return `${styles.modifier[key]}${value}${styles.modifier.reset}`;
+}
+
+function toColorValue(key: Color, value: string): string {
+ return `${styles.color[key]}${value}${styles.modifier.reset}`;
+}
+
+function toBGColorValue(key: BGColor, value: string): string {
+ return `${styles.bgColor[key]}${value}${styles.modifier.reset}`;
+}
+
+type Chalk = Record string> & {
+ color(hex: HexValue): (value: string) => string;
+ bgColor(hex: HexValue): (value: string) => string;
+};
diff --git a/api/libraries/logger/color/hex.ts b/api/libraries/logger/color/hex.ts
new file mode 100644
index 0000000..8ace2db
--- /dev/null
+++ b/api/libraries/logger/color/hex.ts
@@ -0,0 +1,28 @@
+import { rgbToAnsi256 } from "./rgb.ts";
+
+/**
+ * Convert provided hex value to closest 256-Color value.
+ *
+ * @param hex - Hex to convert.
+ */
+export function hexToAnsi256(hex: HexValue) {
+ const { r, g, b } = hexToRGB(hex);
+ return rgbToAnsi256(r, g, b);
+}
+
+/**
+ * Take a hex value and return its RGB values.
+ *
+ * @param hex - Hex to convert to RGB
+ * @returns
+ */
+export function hexToRGB(hex: HexValue): { r: number; g: number; b: number } {
+ return {
+ r: parseInt(hex.slice(1, 3), 16),
+ g: parseInt(hex.slice(3, 5), 16),
+ b: parseInt(hex.slice(5, 7), 16),
+ };
+}
+
+export type HexValue =
+ `#${string | number}${string | number}${string | number}${string | number}${string | number}${string | number}`;
diff --git a/api/libraries/logger/color/rgb.ts b/api/libraries/logger/color/rgb.ts
new file mode 100644
index 0000000..f28f096
--- /dev/null
+++ b/api/libraries/logger/color/rgb.ts
@@ -0,0 +1,24 @@
+/**
+ * Convert RGB to the nearest 256-color ANSI value
+ *
+ * @param r - Red value.
+ * @param g - Green value.
+ * @param b - Blue value.
+ */
+export function rgbToAnsi256(r: number, g: number, b: number): number {
+ if (r === g && g === b) {
+ if (r < 8) return 16;
+ if (r > 248) return 231;
+ return Math.round(((r - 8) / 247) * 24) + 232;
+ }
+
+ // Map RGB to 6×6×6 color cube (16–231)
+ const conv = (val: number) => Math.round(val / 51);
+ const ri = conv(r);
+ const gi = conv(g);
+ const bi = conv(b);
+
+ return 16 + 36 * ri + 6 * gi + bi;
+}
+
+export type RGB = { r: number; g: number; b: number };
diff --git a/api/libraries/logger/color/styles.ts b/api/libraries/logger/color/styles.ts
new file mode 100644
index 0000000..773f53a
--- /dev/null
+++ b/api/libraries/logger/color/styles.ts
@@ -0,0 +1,76 @@
+import { hexToAnsi256, HexValue } from "./hex.ts";
+import { toEscapeSequence } from "./utilities.ts";
+
+export const styles = {
+ modifier: {
+ reset: toEscapeSequence(0), // Reset to normal
+ bold: toEscapeSequence(1), // Bold text
+ dim: toEscapeSequence(2), // Dim text
+ italic: toEscapeSequence(3), // Italic text
+ underline: toEscapeSequence(4), // Underlined text
+ overline: toEscapeSequence(53), // Overline text
+ inverse: toEscapeSequence(7), // Inverse
+ hidden: toEscapeSequence(8), // Hidden text
+ strikethrough: toEscapeSequence(9), // Strikethrough
+ },
+
+ color: {
+ black: toEscapeSequence(30), // Black color
+ red: toEscapeSequence(31), // Red color
+ green: toEscapeSequence(32), // Green color
+ yellow: toEscapeSequence(33), // Yellow color
+ blue: toEscapeSequence(34), // Blue color
+ magenta: toEscapeSequence(35), // Magenta color
+ cyan: toEscapeSequence(36), // Cyan color
+ white: toEscapeSequence(37), // White color
+ orange: hexToColor("#FFA500"),
+
+ // Bright colors
+ blackBright: toEscapeSequence(90),
+ gray: toEscapeSequence(90), // Alias for blackBright
+ grey: toEscapeSequence(90), // Alias for blackBright
+ redBright: toEscapeSequence(91),
+ greenBright: toEscapeSequence(92),
+ yellowBright: toEscapeSequence(93),
+ blueBright: toEscapeSequence(94),
+ magentaBright: toEscapeSequence(95),
+ cyanBright: toEscapeSequence(96),
+ whiteBright: toEscapeSequence(97),
+ },
+
+ bgColor: {
+ bgBlack: toEscapeSequence(40),
+ bgRed: toEscapeSequence(41),
+ bgGreen: toEscapeSequence(42),
+ bgYellow: toEscapeSequence(43),
+ bgBlue: toEscapeSequence(44),
+ bgMagenta: toEscapeSequence(45),
+ bgCyan: toEscapeSequence(46),
+ bgWhite: toEscapeSequence(47),
+ bgOrange: hexToBgColor("#FFA500"),
+
+ // Bright background colors
+ bgBlackBright: toEscapeSequence(100),
+ bgGray: toEscapeSequence(100), // Alias for bgBlackBright
+ bgGrey: toEscapeSequence(100), // Alias for bgBlackBright
+ bgRedBright: toEscapeSequence(101),
+ bgGreenBright: toEscapeSequence(102),
+ bgYellowBright: toEscapeSequence(103),
+ bgBlueBright: toEscapeSequence(104),
+ bgMagentaBright: toEscapeSequence(105),
+ bgCyanBright: toEscapeSequence(106),
+ bgWhiteBright: toEscapeSequence(107),
+ },
+};
+
+export function hexToColor(hex: HexValue): string {
+ return toEscapeSequence(`38;5;${hexToAnsi256(hex)}`); // Foreground color
+}
+
+export function hexToBgColor(hex: HexValue): string {
+ return toEscapeSequence(`48;5;${hexToAnsi256(hex)}`); // Background color
+}
+
+export type Modifier = keyof typeof styles.modifier;
+export type Color = keyof typeof styles.color;
+export type BGColor = keyof typeof styles.bgColor;
diff --git a/api/libraries/logger/color/utilities.ts b/api/libraries/logger/color/utilities.ts
new file mode 100644
index 0000000..50a9fbd
--- /dev/null
+++ b/api/libraries/logger/color/utilities.ts
@@ -0,0 +1,3 @@
+export function toEscapeSequence(value: string | number): `\x1b[${string}m` {
+ return `\x1b[${value}m`;
+}
diff --git a/api/libraries/logger/config.ts b/api/libraries/logger/config.ts
new file mode 100644
index 0000000..72816f5
--- /dev/null
+++ b/api/libraries/logger/config.ts
@@ -0,0 +1,5 @@
+import { getArgsVariable } from "~libraries/config/mod.ts";
+
+export const config = {
+ level: getArgsVariable("LOG_LEVEL", "info"),
+};
diff --git a/api/libraries/logger/format/event-store.ts b/api/libraries/logger/format/event-store.ts
new file mode 100644
index 0000000..a78b827
--- /dev/null
+++ b/api/libraries/logger/format/event-store.ts
@@ -0,0 +1,19 @@
+import { EventValidationError } from "@valkyr/event-store";
+
+import type { Level } from "../level.ts";
+import { getTracedAt } from "../stack.ts";
+
+export function toEventStoreLog(arg: any, level: Level): any {
+ if (arg instanceof EventValidationError) {
+ const obj: any = {
+ origin: "EventStore",
+ message: arg.message,
+ at: getTracedAt(arg.stack, "/api/domains"),
+ data: arg.errors,
+ };
+ if (level === "debug") {
+ obj.stack = arg.stack;
+ }
+ return obj;
+ }
+}
diff --git a/api/libraries/logger/format/server.ts b/api/libraries/logger/format/server.ts
new file mode 100644
index 0000000..ba8e8ea
--- /dev/null
+++ b/api/libraries/logger/format/server.ts
@@ -0,0 +1,18 @@
+import { ServerError } from "@spec/relay";
+
+import type { Level } from "../level.ts";
+import { getTracedAt } from "../stack.ts";
+
+export function toServerLog(arg: any, level: Level): any {
+ if (arg instanceof ServerError) {
+ const obj: any = {
+ message: arg.message,
+ data: arg.data,
+ at: getTracedAt(arg.stack, "/api/domains"),
+ };
+ if (level === "debug") {
+ obj.stack = arg.stack;
+ }
+ return obj;
+ }
+}
diff --git a/api/libraries/logger/level.ts b/api/libraries/logger/level.ts
new file mode 100644
index 0000000..095af5b
--- /dev/null
+++ b/api/libraries/logger/level.ts
@@ -0,0 +1,8 @@
+export const logLevel = {
+ debug: 0,
+ info: 1,
+ warning: 2,
+ error: 3,
+};
+
+export type Level = "debug" | "error" | "warning" | "info";
diff --git a/api/libraries/logger/logger.ts b/api/libraries/logger/logger.ts
new file mode 100644
index 0000000..0a8f115
--- /dev/null
+++ b/api/libraries/logger/logger.ts
@@ -0,0 +1,95 @@
+import { chalk } from "./chalk.ts";
+import { type Level, logLevel } from "./level.ts";
+
+export class Logger {
+ #level: Level = "info";
+ #config: Config;
+
+ constructor(config: Config) {
+ this.#config = config;
+ }
+
+ get #prefix(): [string?] {
+ if (this.#config.prefix !== undefined) {
+ return [chalk.bold(chalk.green(this.#config.prefix))];
+ }
+ return [];
+ }
+
+ /**
+ * Set the highest logging level in the order of debug, info, warn, error.
+ *
+ * When value is 'info', info, warn and error will be logged and debug
+ * will be ignored.
+ *
+ * @param value Highest log level.
+ */
+ level(value: Level): this {
+ this.#level = value;
+ return this;
+ }
+
+ /**
+ * Returns a new logger instance with the given name as prefix.
+ *
+ * @param name - Prefix name.
+ */
+ prefix(name: string): Logger {
+ return new Logger({ prefix: name, loggers: this.#config.loggers }).level(this.#level);
+ }
+
+ /**
+ * Emit a debug message to terminal.
+ */
+ debug(...args: any[]) {
+ if (this.#isLevelEnabled(0)) {
+ console.log(new Date(), chalk.bold("Debug"), ...this.#prefix, ...args.map(this.#toFormattedArg));
+ }
+ }
+
+ /**
+ * Emit a info message to terminal.
+ */
+ info(...args: any[]) {
+ if (this.#isLevelEnabled(1)) {
+ console.log(new Date(), chalk.bold(chalk.blue("Info")), ...this.#prefix, ...args.map(this.#toFormattedArg));
+ }
+ }
+
+ /**
+ * Emit a warning message to terminal.
+ */
+ warn(...args: any[]) {
+ if (this.#isLevelEnabled(2)) {
+ console.log(new Date(), chalk.bold(chalk.orange("Warning")), ...this.#prefix, ...args.map(this.#toFormattedArg));
+ }
+ }
+
+ /**
+ * Emit a errpr message to terminal.
+ */
+ error(...args: any[]) {
+ if (this.#isLevelEnabled(3)) {
+ console.log(new Date(), chalk.bold(chalk.red("Error")), ...this.#prefix, ...args.map(this.#toFormattedArg));
+ }
+ }
+
+ #isLevelEnabled(level: 0 | 1 | 2 | 3): boolean {
+ return level >= logLevel[this.#level];
+ }
+
+ #toFormattedArg = (arg: any): string => {
+ for (const logger of this.#config.loggers) {
+ const res = logger(arg, this.#level);
+ if (res !== undefined) {
+ return res;
+ }
+ }
+ return arg;
+ };
+}
+
+type Config = {
+ prefix?: string;
+ loggers: ((arg: any, level: Level) => any)[];
+};
diff --git a/api/libraries/logger/mod.ts b/api/libraries/logger/mod.ts
new file mode 100644
index 0000000..9fd6623
--- /dev/null
+++ b/api/libraries/logger/mod.ts
@@ -0,0 +1,7 @@
+import { toEventStoreLog } from "./format/event-store.ts";
+import { toServerLog } from "./format/server.ts";
+import { Logger } from "./logger.ts";
+
+export const logger = new Logger({
+ loggers: [toServerLog, toEventStoreLog],
+});
diff --git a/api/libraries/logger/stack.ts b/api/libraries/logger/stack.ts
new file mode 100644
index 0000000..f6d4501
--- /dev/null
+++ b/api/libraries/logger/stack.ts
@@ -0,0 +1,20 @@
+/**
+ * Fetch the most closest relevant error from the local code base so it can
+ * be more easily traced to its source.
+ *
+ * @param stack - Error stack.
+ * @param search - Relevant stack line search value.
+ */
+export function getTracedAt(stack: string | undefined, search: string): string | undefined {
+ if (stack === undefined) {
+ return undefined;
+ }
+ const firstMatch = stack.split("\n").find((line) => line.includes(search));
+ if (firstMatch === undefined) {
+ return undefined;
+ }
+ return firstMatch
+ .replace(/^.*?(file:\/\/\/)/, "$1")
+ .replace(/\)$/, "")
+ .trim();
+}
diff --git a/api/libraries/read-store/.tasks/bootstrap.ts b/api/libraries/read-store/.tasks/bootstrap.ts
new file mode 100644
index 0000000..32ddac9
--- /dev/null
+++ b/api/libraries/read-store/.tasks/bootstrap.ts
@@ -0,0 +1,11 @@
+import { idIndex } from "~libraries/database/id.ts";
+import { register } from "~libraries/database/registrar.ts";
+
+import { db } from "../database.ts";
+
+await register(db.db, [
+ {
+ name: "accounts",
+ indexes: [idIndex],
+ },
+]);
diff --git a/api/libraries/read-store/account/methods.ts b/api/libraries/read-store/account/methods.ts
new file mode 100644
index 0000000..510393b
--- /dev/null
+++ b/api/libraries/read-store/account/methods.ts
@@ -0,0 +1,6 @@
+import { db, takeOne } from "../database.ts";
+import { type AccountSchema, fromAccountDriver } from "./schema.ts";
+
+export async function getAccountById(id: string): Promise {
+ return db.collection("accounts").find({ id }).toArray().then(fromAccountDriver).then(takeOne);
+}
diff --git a/api/libraries/read-store/account/schema.ts b/api/libraries/read-store/account/schema.ts
new file mode 100644
index 0000000..7e74c30
--- /dev/null
+++ b/api/libraries/read-store/account/schema.ts
@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+const account = z.object({
+ id: z.uuid(),
+ name: z.object({
+ given: z.string(),
+ family: z.string(),
+ }),
+ email: z.email(),
+});
+
+/*
+ |--------------------------------------------------------------------------------
+ | Parsers
+ |--------------------------------------------------------------------------------
+ */
+
+const select = account;
+const insert = account;
+
+export function toAccountDriver(documents: unknown): AccountInsert {
+ return insert.parse(documents);
+}
+
+export function fromAccountDriver(documents: unknown[]): AccountSchema[] {
+ return documents.map((document) => select.parse(document));
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Types
+ |--------------------------------------------------------------------------------
+ */
+
+export type AccountSchema = z.infer;
+export type AccountInsert = z.infer;
diff --git a/api/libraries/read-store/database.ts b/api/libraries/read-store/database.ts
new file mode 100644
index 0000000..f2d0452
--- /dev/null
+++ b/api/libraries/read-store/database.ts
@@ -0,0 +1,12 @@
+import { config } from "~config";
+import { getDatabaseAccessor } from "~libraries/database/accessor.ts";
+
+import { AccountInsert } from "./account/schema.ts";
+
+export const db = getDatabaseAccessor<{
+ accounts: AccountInsert;
+}>(`${config.name}:read-store`);
+
+export function takeOne(documents: TDocument[]): TDocument | undefined {
+ return documents[0];
+}
diff --git a/api/libraries/read-store/mod.ts b/api/libraries/read-store/mod.ts
new file mode 100644
index 0000000..739683a
--- /dev/null
+++ b/api/libraries/read-store/mod.ts
@@ -0,0 +1,3 @@
+export * from "./account/methods.ts";
+export * from "./account/schema.ts";
+export * from "./database.ts";
diff --git a/api/libraries/server/api.ts b/api/libraries/server/api.ts
new file mode 100644
index 0000000..0c36bfe
--- /dev/null
+++ b/api/libraries/server/api.ts
@@ -0,0 +1,415 @@
+import {
+ BadRequestError,
+ ForbiddenError,
+ InternalServerError,
+ NotFoundError,
+ NotImplementedError,
+ Route,
+ RouteMethod,
+ ServerError,
+ type ServerErrorResponse,
+ UnauthorizedError,
+ ZodValidationError,
+} from "@spec/relay";
+import { treeifyError } from "zod";
+
+import { logger } from "~libraries/logger/mod.ts";
+
+import { getRequestContext } from "./context.ts";
+import { req } from "./request.ts";
+
+const SUPPORTED_MEHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+export class Api {
+ readonly #index = new Map();
+
+ /**
+ * Route maps funneling registered routes to the specific methods supported by
+ * the relay instance.
+ */
+ readonly routes: Routes = {
+ POST: [],
+ GET: [],
+ PUT: [],
+ PATCH: [],
+ DELETE: [],
+ };
+
+ /**
+ * List of paths in the '${method} ${path}' format allowing us to quickly throw
+ * errors if a duplicate route path is being added.
+ */
+ readonly #paths = new Set();
+
+ /**
+ * Instantiate a new Api instance.
+ *
+ * @param routes - Initial list of routes to register with the api.
+ */
+ constructor(routes: Route[] = []) {
+ this.register(routes);
+ }
+
+ /**
+ * Register relays with the API instance allowing for decoupled registration
+ * of server side handling of relay contracts.
+ *
+ * @param routes - Relays to register with the instance.
+ */
+ register(routes: Route[]): this {
+ const methods: (keyof typeof this.routes)[] = [];
+ for (const route of routes) {
+ const path = `${route.method} ${route.path}`;
+ if (this.#paths.has(path)) {
+ throw new Error(`Router > Path ${path} already exists`);
+ }
+ this.#paths.add(path);
+ this.routes[route.method].push(route);
+ methods.push(route.method);
+ this.#index.set(`${route.method} ${route.path}`, route);
+ }
+ for (const method of methods) {
+ this.routes[method].sort(byStaticPriority);
+ }
+ return this;
+ }
+
+ /**
+ * Executes request and returns a `Response` instance.
+ *
+ * @param request - REST request to pass to a route handler.
+ */
+ async fetch(request: Request): Promise {
+ const url = new URL(request.url);
+
+ // ### Route
+ // Locate a route matching the incoming request method and path.
+
+ const resolved = this.#getResolvedRoute(request.method, url.pathname);
+ if (resolved === undefined) {
+ return toResponse(
+ new NotFoundError(`Invalid routing path provided for ${request.url}`, {
+ method: request.method,
+ url: request.url,
+ }),
+ request,
+ );
+ }
+
+ // ### Handle
+ // Execute request and return a response.
+
+ const response = await this.#getRouteResponse(resolved, request).catch((error) =>
+ this.#getErrorResponse(error, resolved.route, request),
+ );
+
+ return response;
+ }
+
+ /**
+ * Attempt to resolve a route based on the given method and pathname.
+ *
+ * @param method - HTTP method.
+ * @param url - HTTP request url.
+ */
+ #getResolvedRoute(method: string, url: string): ResolvedRoute | undefined {
+ assertMethod(method);
+ for (const route of this.routes[method]) {
+ if (route.match(url) === true) {
+ return { route, params: route.getParsedParams(url) };
+ }
+ }
+ }
+
+ /**
+ * Resolve the request on the given route and return a `Response` instance.
+ *
+ * @param resolved - Route and paramter details resolved for the request.
+ * @param request - Request instance to resolve.
+ */
+ async #getRouteResponse({ route, params }: ResolvedRoute, request: Request): Promise {
+ const url = new URL(request.url);
+
+ // ### Args
+ // Arguments is passed to every route handler and provides a suite of functionality
+ // and request data.
+
+ const args: any[] = [];
+
+ // ### Input
+ // Generate route input which contains a map fo params, query, and/or body. If
+ // none of these are present then the input is not added to the final argument
+ // context of the handler.
+
+ const input: {
+ params?: object;
+ query?: object;
+ body?: unknown;
+ } = {
+ params: undefined,
+ query: undefined,
+ body: undefined,
+ };
+
+ // ### Access
+ // Check the access requirements of the route and run any additional checks
+ // if nessesary before proceeding with further request handling.
+ // 1. All routes needs access assignment, else we consider it an internal error.
+ // 2. If access requires a session we throw Unauthorized if the request is not authenticated.
+ // 3. If access is an array of access resources, we check that each resources can be
+ // accessed by the request.
+
+ if (route.state.access === undefined) {
+ return toResponse(
+ new InternalServerError(`Route '${route.method} ${route.path}' is missing access assignment.`),
+ request,
+ );
+ }
+
+ if (route.state.access === "session" && req.isAuthenticated === false) {
+ return toResponse(new UnauthorizedError(), request);
+ }
+
+ if (Array.isArray(route.state.access)) {
+ for (const hasAccess of route.state.access) {
+ if (hasAccess() === false) {
+ return toResponse(new ForbiddenError(), request);
+ }
+ }
+ }
+
+ // ### Params
+ // If the route has params we want to coerce the values to the expected types.
+
+ if (route.state.params !== undefined) {
+ const result = await route.state.params.safeParseAsync(params);
+ if (result.success === false) {
+ return toResponse(new ZodValidationError("Invalid request params", treeifyError(result.error)), request);
+ }
+ input.params = result.data;
+ }
+
+ // ### Query
+ // If the route has a query schema we need to validate and parse the query.
+
+ if (route.state.query !== undefined) {
+ const result = await route.state.query.safeParseAsync(toQuery(url.searchParams) ?? {});
+ if (result.success === false) {
+ return toResponse(new ZodValidationError("Invalid request query", treeifyError(result.error)), request);
+ }
+ input.query = result.data;
+ }
+
+ // ### Body
+ // If the route has a body schema we need to validate and parse the body.
+
+ if (route.state.body !== undefined) {
+ const body = await this.#getRequestBody(request);
+ const result = await route.state.body.safeParseAsync(body);
+ if (result.success === false) {
+ return toResponse(new ZodValidationError("Invalid request body", treeifyError(result.error)), request);
+ }
+ input.body = result.data;
+ }
+
+ if (input.params !== undefined || input.query !== undefined || input.body !== undefined) {
+ args.push(input);
+ }
+
+ // ### Context
+ // Request context pass to every route as the last argument.
+
+ args.push(getRequestContext(request));
+
+ // ### Handler
+ // Execute the route handler and apply the result.
+
+ if (route.state.handle === undefined) {
+ return toResponse(new NotImplementedError(`Path '${route.method} ${route.path}' is not implemented.`), request);
+ }
+
+ return toResponse(await route.state.handle(...args), request);
+ }
+
+ #getErrorResponse(error: unknown, route: Route, request: Request): Response {
+ if (route?.state.hooks?.onError !== undefined) {
+ return route.state.hooks.onError(error);
+ }
+ if (error instanceof ServerError) {
+ return toResponse(error, request);
+ }
+ logger.error(error);
+ if (error instanceof Error) {
+ return toResponse(new InternalServerError(error.message), request);
+ }
+ return toResponse(new InternalServerError(), request);
+ }
+
+ /**
+ * Resolves request body and returns it.
+ *
+ * @param request - Request to resolve body from.
+ * @param files - Files to populate if present.
+ */
+ async #getRequestBody(request: Request): Promise> {
+ let body: Record = {};
+
+ const type = request.headers.get("content-type");
+ if (!type || request.method === "GET") {
+ return body;
+ }
+
+ if (type.includes("json")) {
+ body = await request.json();
+ }
+
+ if (type.includes("application/x-www-form-urlencoded") || type.includes("multipart/form-data")) {
+ try {
+ const formData = await request.formData();
+ for (const [name, value] of Array.from(formData.entries())) {
+ body[name] = value;
+ }
+ } catch (error) {
+ logger.error(error);
+ throw new BadRequestError(`Malformed FormData`, { error });
+ }
+ }
+
+ return body;
+ }
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Helpers
+ |--------------------------------------------------------------------------------
+ */
+
+/**
+ * Assert that the given method string is a valid routing method.
+ *
+ * @param candidate - Method candidate.
+ */
+function assertMethod(candidate: string): asserts candidate is RouteMethod {
+ if (!SUPPORTED_MEHODS.includes(candidate)) {
+ throw new Error(`Router > Unsupported method '${candidate}'`);
+ }
+}
+
+/**
+ * Sorting method for routes to ensure that static properties takes precedence
+ * for when a route is matched against incoming requests.
+ *
+ * @param a - Route A
+ * @param b - Route B
+ */
+function byStaticPriority(a: Route, b: Route) {
+ const aSegments = a.path.split("/");
+ const bSegments = b.path.split("/");
+
+ const maxLength = Math.max(aSegments.length, bSegments.length);
+
+ for (let i = 0; i < maxLength; i++) {
+ const aSegment = aSegments[i] || "";
+ const bSegment = bSegments[i] || "";
+
+ const isADynamic = aSegment.startsWith(":");
+ const isBDynamic = bSegment.startsWith(":");
+
+ if (isADynamic !== isBDynamic) {
+ return isADynamic ? 1 : -1;
+ }
+
+ if (isADynamic === false && aSegment !== bSegment) {
+ return aSegment.localeCompare(bSegment);
+ }
+ }
+
+ return a.path.localeCompare(b.path);
+}
+
+/**
+ * Resolve and return query object from the provided search parameters, or undefined
+ * if the search parameters does not have any entries.
+ *
+ * @param searchParams - Search params to create a query object from.
+ */
+function toQuery(searchParams: URLSearchParams): object | undefined {
+ if (searchParams.size === 0) {
+ return undefined;
+ }
+ const result: Record = {};
+ for (const [key, value] of searchParams.entries()) {
+ result[key] = value;
+ }
+ return result;
+}
+
+/**
+ * Takes a server side request result and returns a fetch Response.
+ *
+ * @param result - Result to send back as a Response.
+ * @param request - Request instance.
+ */
+export function toResponse(result: unknown, request: Request): Response {
+ const method = request.method;
+
+ if (result instanceof Response) {
+ if (method === "HEAD") {
+ return new Response(null, {
+ status: result.status,
+ statusText: result.statusText,
+ headers: new Headers(result.headers),
+ });
+ }
+ return result;
+ }
+
+ if (result instanceof ServerError) {
+ const body = JSON.stringify({
+ error: {
+ status: result.status,
+ message: result.message,
+ data: result.data,
+ },
+ } satisfies ServerErrorResponse);
+
+ return new Response(method === "HEAD" ? null : body, {
+ statusText: result.message || "Internal Server Error",
+ status: result.status || 500,
+ headers: {
+ "content-type": "application/json",
+ },
+ });
+ }
+
+ const body = JSON.stringify({
+ data: result ?? null,
+ });
+
+ return new Response(method === "HEAD" ? null : body, {
+ status: 200,
+ headers: {
+ "content-type": "application/json",
+ },
+ });
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Types
+ |--------------------------------------------------------------------------------
+ */
+
+type Routes = {
+ POST: Route[];
+ GET: Route[];
+ PUT: Route[];
+ PATCH: Route[];
+ DELETE: Route[];
+};
+
+type ResolvedRoute = {
+ route: Route;
+ params: any;
+};
diff --git a/api/libraries/server/context.ts b/api/libraries/server/context.ts
new file mode 100644
index 0000000..d77d389
--- /dev/null
+++ b/api/libraries/server/context.ts
@@ -0,0 +1,16 @@
+import { RouteContext } from "@spec/relay";
+
+export function getRequestContext(request: Request): RouteContext {
+ return {
+ request,
+ };
+}
+
+declare module "@spec/relay" {
+ interface RouteContext {
+ /**
+ * Current request instance being handled.
+ */
+ request: Request;
+ }
+}
diff --git a/api/libraries/server/mod.ts b/api/libraries/server/mod.ts
new file mode 100644
index 0000000..316ad24
--- /dev/null
+++ b/api/libraries/server/mod.ts
@@ -0,0 +1,5 @@
+export * from "./api.ts";
+export * from "./context.ts";
+export * from "./modules.ts";
+export * from "./request.ts";
+export * from "./storage.ts";
diff --git a/api/libraries/server/modules.ts b/api/libraries/server/modules.ts
new file mode 100644
index 0000000..bc3752e
--- /dev/null
+++ b/api/libraries/server/modules.ts
@@ -0,0 +1,40 @@
+import { Route } from "@spec/relay";
+
+/**
+ * Resolve and return all routes that has been created under any 'routes'
+ * folders that can be found under the given path.
+ *
+ * If the filter is empty, all paths are resolved, otherwise only paths
+ * declared in the array is resolved.
+ *
+ * @param path - Path to resolve routes from.
+ * @param filter - List of modules to include.
+ * @param routes - List of routes that has been resolved.
+ */
+export async function resolveRoutes(path: string, routes: Route[] = []): Promise {
+ for await (const entry of Deno.readDir(path)) {
+ if (entry.isDirectory === true) {
+ await loadRoutes(`${path}/${entry.name}/routes`, routes, [name]);
+ }
+ }
+ return routes;
+}
+
+async function loadRoutes(path: string, routes: Route[], modules: string[]): Promise {
+ for await (const entry of Deno.readDir(path)) {
+ if (entry.isDirectory === true) {
+ await loadRoutes(`${path}/${entry.name}`, routes, [...modules, entry.name]);
+ } else {
+ if (!entry.name.endsWith(".ts") || entry.name.endsWith("i9n.ts")) {
+ continue;
+ }
+ const { default: route } = (await import(`${path}/${entry.name}`)) as { default: Route };
+ if (route instanceof Route === false) {
+ throw new Error(
+ `Router Violation: Could not load '${path}/${entry.name}' as it does not export a default Route instance.`,
+ );
+ }
+ routes.push(route);
+ }
+ }
+}
diff --git a/api/libraries/server/request.ts b/api/libraries/server/request.ts
new file mode 100644
index 0000000..c6d4678
--- /dev/null
+++ b/api/libraries/server/request.ts
@@ -0,0 +1,57 @@
+import { asyncLocalStorage } from "./storage.ts";
+
+export const req = {
+ get store() {
+ const store = asyncLocalStorage.getStore();
+ if (store === undefined) {
+ throw new Error("Request > AsyncLocalStorage not defined.");
+ }
+ return store;
+ },
+
+ get socket() {
+ return this.store.socket;
+ },
+
+ /**
+ * Get store that is potentially undefined.
+ * Typically used when utility functions might run in and out of request scope.
+ */
+ get unsafeStore() {
+ return asyncLocalStorage.getStore();
+ },
+
+ /**
+ * Check if the request is authenticated.
+ */
+ get isAuthenticated() {
+ return this.session !== undefined;
+ },
+
+ /**
+ * Get current session.
+ */
+ get session() {
+ return this.store.session;
+ },
+
+ /**
+ * Gets the meta information stored in the request.
+ */
+ get info() {
+ return this.store.info;
+ },
+
+ /**
+ * Sends a JSON-RPC 2.0 notification to the request if sent through a
+ * WebSocket connection.
+ *
+ * @param method - Method to send notification to.
+ * @param params - Params to pass to the method.
+ */
+ notify(method: string, params: any): void {
+ this.socket?.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
+ },
+} as const;
+
+export type ReqContext = typeof req;
diff --git a/api/libraries/server/storage.ts b/api/libraries/server/storage.ts
new file mode 100644
index 0000000..3cdf826
--- /dev/null
+++ b/api/libraries/server/storage.ts
@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { Session } from "~libraries/auth/mod.ts";
+
+export const asyncLocalStorage = new AsyncLocalStorage<{
+ session?: Session;
+ info: {
+ method: string;
+ start: number;
+ end?: number;
+ };
+ socket?: WebSocket;
+ response: {
+ headers: Headers;
+ };
+}>();
diff --git a/api/libraries/socket/channels.ts b/api/libraries/socket/channels.ts
new file mode 100644
index 0000000..6653dd8
--- /dev/null
+++ b/api/libraries/socket/channels.ts
@@ -0,0 +1,81 @@
+import type { Params } from "@valkyr/json-rpc";
+
+import { Sockets } from "./sockets.ts";
+
+export class Channels {
+ readonly #channels = new Map();
+
+ /**
+ * Add a new channel.
+ *
+ * @param channel
+ */
+ add(channel: string): this {
+ this.#channels.set(channel, new Sockets());
+ return this;
+ }
+
+ /**
+ * Deletes a channel.
+ *
+ * @param channel
+ */
+ del(channel: string): this {
+ this.#channels.delete(channel);
+ return this;
+ }
+
+ /**
+ * Add socket to the given channel. If the channel does not exist it is
+ * automatically created.
+ *
+ * @param channel - Channel to add socket to.
+ * @param socket - Socket to add to the channel.
+ */
+ join(channel: string, socket: WebSocket): this {
+ const sockets = this.#channels.get(channel);
+ if (sockets === undefined) {
+ this.#channels.set(channel, new Sockets().add(socket));
+ } else {
+ sockets.add(socket);
+ }
+ return this;
+ }
+
+ /**
+ * Remove a socket from the given channel.
+ *
+ * @param channel - Channel to leave.
+ * @param socket - Socket to remove from the channel.
+ */
+ leave(channel: string, socket: WebSocket): this {
+ this.#channels.get(channel)?.del(socket);
+ return this;
+ }
+
+ /**
+ * Sends a JSON-RPC notification to all sockets in given channel.
+ *
+ * @param channel - Channel to emit method to.
+ * @param method - Method to send the notification to.
+ * @param params - Message data to send to the clients.
+ */
+ notify(channel: string, method: string, params: Params): this {
+ this.#channels.get(channel)?.notify(method, params);
+ return this;
+ }
+
+ /**
+ * Transmits data to all registered WebSocket connections in the given channel.
+ * Data can be a string, a Blob, an ArrayBuffer, or an ArrayBufferView.
+ *
+ * @param channel - Channel to emit message to.
+ * @param data - Data to send to each connected socket in the channel.
+ */
+ send(channel: string, data: string | ArrayBufferLike | Blob | ArrayBufferView): this {
+ this.#channels.get(channel)?.send(data);
+ return this;
+ }
+}
+
+export const channels = new Channels();
diff --git a/api/libraries/socket/mod.ts b/api/libraries/socket/mod.ts
new file mode 100644
index 0000000..8496e56
--- /dev/null
+++ b/api/libraries/socket/mod.ts
@@ -0,0 +1 @@
+export { Sockets } from "./sockets.ts";
diff --git a/api/libraries/socket/sockets.ts b/api/libraries/socket/sockets.ts
new file mode 100644
index 0000000..fc981e9
--- /dev/null
+++ b/api/libraries/socket/sockets.ts
@@ -0,0 +1,49 @@
+import type { Params } from "@valkyr/json-rpc";
+
+export class Sockets {
+ readonly #sockets = new Set();
+
+ /**
+ * Add a socket to the pool.
+ *
+ * @param socket - WebSocket to add.
+ */
+ add(socket: WebSocket): this {
+ this.#sockets.add(socket);
+ return this;
+ }
+
+ /**
+ * Remove a socket from the pool.
+ *
+ * @param socket - WebSocket to remove.
+ */
+ del(socket: WebSocket): this {
+ this.#sockets.delete(socket);
+ return this;
+ }
+
+ /**
+ * Sends a JSON-RPC notification to all connected sockets.
+ *
+ * @param method - Method to send the notification to.
+ * @param params - Message data to send to the clients.
+ */
+ notify(method: string, params: Params): this {
+ this.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
+ return this;
+ }
+
+ /**
+ * Transmits data to all registered WebSocket connections. Data can be a string,
+ * a Blob, an ArrayBuffer, or an ArrayBufferView.
+ *
+ * @param data - Data to send to each connected socket.
+ */
+ send(data: string | ArrayBufferLike | Blob | ArrayBufferView): this {
+ this.#sockets.forEach((socket) => socket.send(data));
+ return this;
+ }
+}
+
+export const sockets = new Sockets();
diff --git a/api/libraries/socket/upgrade.ts b/api/libraries/socket/upgrade.ts
new file mode 100644
index 0000000..3bc7962
--- /dev/null
+++ b/api/libraries/socket/upgrade.ts
@@ -0,0 +1,60 @@
+import { toJsonRpc } from "@valkyr/json-rpc";
+
+import { Session } from "~libraries/auth/mod.ts";
+import { logger } from "~libraries/logger/mod.ts";
+
+import { sockets } from "./sockets.ts";
+
+export function upgrade(request: Request, session?: Session) {
+ const { socket, response } = Deno.upgradeWebSocket(request);
+
+ socket.addEventListener("open", () => {
+ logger.prefix("Socket").info("socket connected", { session });
+ sockets.add(socket);
+ });
+
+ socket.addEventListener("close", () => {
+ logger.prefix("Socket").info("socket disconnected", { session });
+ sockets.del(socket);
+ });
+
+ socket.addEventListener("message", (event) => {
+ if (event.data === "ping") {
+ return;
+ }
+
+ const body = toJsonRpc(event.data);
+
+ logger.prefix("Socket").info(body);
+
+ asyncLocalStorage.run(
+ {
+ session,
+ info: {
+ method: body.method!,
+ start: Date.now(),
+ },
+ socket,
+ response: {
+ headers: new Headers(),
+ },
+ },
+ async () => {
+ api
+ .handleCommand(body)
+ .then((response) => {
+ if (response !== undefined) {
+ logger.info({ response });
+ socket.send(JSON.stringify(response));
+ }
+ })
+ .catch((error) => {
+ logger.info({ error });
+ socket.send(JSON.stringify(error));
+ });
+ },
+ );
+ });
+
+ return response;
+}
diff --git a/api/libraries/testing/config.ts b/api/libraries/testing/config.ts
new file mode 100644
index 0000000..ec1583b
--- /dev/null
+++ b/api/libraries/testing/config.ts
@@ -0,0 +1,4 @@
+export const config = {
+ mongodb: "mongo:8.0.3",
+ postgres: "postgres:17",
+};
diff --git a/api/libraries/testing/containers/api-container.ts b/api/libraries/testing/containers/api-container.ts
new file mode 100644
index 0000000..b82eff7
--- /dev/null
+++ b/api/libraries/testing/containers/api-container.ts
@@ -0,0 +1,154 @@
+import { getAvailablePort } from "@std/net";
+import cookie from "cookie";
+
+import { auth, Session } from "~libraries/auth/mod.ts";
+import { Code } from "~libraries/code/aggregates/code.ts";
+import { handler } from "~libraries/server/handler.ts";
+
+import { Api, QueryMethod } from "../.generated/api.ts";
+
+export class ApiTestContainer {
+ #server?: Deno.HttpServer;
+ #client?: Api;
+ #cookie?: string;
+ #session?: Session;
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Accessors
+ |--------------------------------------------------------------------------------
+ */
+
+ get accountId(): string | undefined {
+ if (this.#session?.valid === true) {
+ return this.#session.accountId;
+ }
+ }
+
+ get client() {
+ if (this.#client === undefined) {
+ throw new Error("ApiContainer > .start() has not been executed.");
+ }
+ return this.#client;
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Lifecycle
+ |--------------------------------------------------------------------------------
+ */
+
+ async start(): Promise {
+ const port = await getAvailablePort();
+ this.#server = await Deno.serve({ port, hostname: "127.0.0.1" }, handler);
+ this.#client = makeApiClient(port, {
+ onBeforeRequest: (headers: Headers) => {
+ if (this.#cookie !== undefined) {
+ headers.set("cookie", this.#cookie);
+ }
+ },
+ onAfterResponse: (response) => {
+ const cookie = response.headers.get("set-cookie");
+ if (cookie !== null) {
+ this.#cookie = cookie;
+ }
+ },
+ });
+ return this;
+ }
+
+ async stop() {
+ await this.#server?.shutdown();
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Utilities
+ |--------------------------------------------------------------------------------
+ */
+
+ async authorize(accountId: string): Promise {
+ const code = await Code.create({ identity: { type: "admin", accountId } }).save();
+ await this.client.auth.code(accountId, code.id, code.value, {});
+ this.#session = await this.getSession();
+ }
+
+ async getSession(): Promise {
+ const token = cookie.parse(this.#cookie ?? "").token;
+ if (token !== undefined) {
+ const session = await auth.resolve(token);
+ if (session.valid === true) {
+ return session;
+ }
+ }
+ }
+
+ unauthorize(): void {
+ this.#cookie = undefined;
+ }
+}
+
+function makeApiClient(
+ port: number,
+ {
+ onBeforeRequest,
+ onAfterResponse,
+ }: {
+ onBeforeRequest: (headers: Headers) => void;
+ onAfterResponse: (response: Response) => void;
+ },
+): Api {
+ return new Api({
+ async command(payload) {
+ const headers = new Headers();
+ onBeforeRequest(headers);
+ headers.set("content-type", "application/json");
+ const response = await fetch(`http://127.0.0.1:${port}/api/v1/command`, {
+ method: "POST",
+ headers,
+ body: JSON.stringify(payload),
+ });
+ const text = await response.text();
+ if (response.status >= 300) {
+ console.error(
+ `Command '${payload.method}' responded with error status '${response.status} ${response.statusText}'.`,
+ );
+ }
+ if (response.headers.get("content-type")?.includes("json") === true) {
+ return JSON.parse(text);
+ }
+ },
+ async query(method: QueryMethod, path: string, query: Record, body: any = {}) {
+ const headers = new Headers();
+ onBeforeRequest(headers);
+ if (method !== "GET") {
+ headers.set("content-type", "application/json");
+ }
+ const response = await fetch(`http://127.0.0.1:${port}${path}${getSearchQuery(query)}`, {
+ method,
+ headers,
+ body: method === "GET" ? undefined : JSON.stringify(body),
+ });
+ onAfterResponse(response);
+ const text = await response.text();
+ if (response.status >= 300) {
+ console.error(`Query '${path}' responded with error status '${response.status} ${response.statusText}'.`);
+ throw new Error(response.statusText);
+ }
+ if (response.headers.get("content-type")?.includes("json") === true) {
+ return JSON.parse(text);
+ }
+ },
+ });
+}
+
+function getSearchQuery(query: Record): string {
+ const search: string[] = [];
+ for (const key in query) {
+ search.push(`${key}=${query[key]}`);
+ }
+ if (search.length === 0) {
+ return "";
+ }
+ return `?${search.join("&")}`;
+}
diff --git a/api/libraries/testing/containers/database-container.ts b/api/libraries/testing/containers/database-container.ts
new file mode 100644
index 0000000..da20da5
--- /dev/null
+++ b/api/libraries/testing/containers/database-container.ts
@@ -0,0 +1,41 @@
+import { MongoTestContainer } from "@valkyr/testcontainers/mongodb";
+
+import { container } from "~database/container.ts";
+import { logger } from "~libraries/logger/mod.ts";
+import { bootstrap } from "~libraries/utilities/bootstrap.ts";
+import { API_DOMAINS_DIR, API_PACKAGES_DIR } from "~paths";
+
+export class DatabaseTestContainer {
+ constructor(readonly mongo: MongoTestContainer) {
+ container.set("client", mongo.client);
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Lifecycle
+ |--------------------------------------------------------------------------------
+ */
+
+ async start(): Promise {
+ logger.prefix("Database").info("DatabaseTestContainer Started");
+
+ await bootstrap(API_DOMAINS_DIR);
+ await bootstrap(API_PACKAGES_DIR);
+
+ return this;
+ }
+
+ async truncate() {
+ const promises: Promise[] = [];
+ for (const dbName of ["balto:auth", "balto:code", "balto:consultant", "balto:task"]) {
+ const db = this.mongo.client.db(dbName);
+ const collections = await db.listCollections().toArray();
+ promises.push(...collections.map(({ name }) => db.collection(name).deleteMany({})));
+ }
+ await Promise.all(promises);
+ }
+
+ async stop() {
+ logger.prefix("Database").info("DatabaseTestContainer stopped");
+ }
+}
diff --git a/api/libraries/testing/containers/test-container.ts b/api/libraries/testing/containers/test-container.ts
new file mode 100644
index 0000000..eb57dd1
--- /dev/null
+++ b/api/libraries/testing/containers/test-container.ts
@@ -0,0 +1,178 @@
+import { MongoTestContainer } from "@valkyr/testcontainers/mongodb";
+
+import { config } from "../config.ts";
+import { ApiTestContainer } from "./api-container.ts";
+import { DatabaseTestContainer } from "./database-container.ts";
+
+export class TestContainer {
+ readonly id = crypto.randomUUID();
+
+ // ### Enablers
+ // A map of services to enable when the TestContainer is started. These toggles
+ // must be toggled before the container is started.
+
+ #with: With = {
+ mongodb: false,
+ database: false,
+ api: false,
+ };
+
+ // ### Needs
+
+ #needs: Needs = {
+ mongodb: [],
+ database: ["mongodb"],
+ api: ["mongodb", "database"],
+ };
+
+ // ### Services
+ // Any services that has been enabled will be running under the following
+ // assignments. Make sure to .stop any running services to avoid shutdown
+ // leaks.
+
+ #mongodb?: MongoTestContainer;
+ #database?: DatabaseTestContainer;
+ #api?: ApiTestContainer;
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Accessors
+ |--------------------------------------------------------------------------------
+ */
+
+ get accountId() {
+ if (this.#api === undefined) {
+ throw new Error("TestContainer > .withApi() must be called before starting the TestContainer.");
+ }
+ return this.#api.accountId;
+ }
+
+ get mongodb(): MongoTestContainer {
+ if (this.#mongodb === undefined) {
+ throw new Error("TestContainer > .withMongo() must be called before starting the TestContainer.");
+ }
+ return this.#mongodb;
+ }
+
+ get database(): DatabaseTestContainer {
+ if (this.#database === undefined) {
+ throw new Error("TestContainer > .withDatabase() must be called before starting the TestContainer.");
+ }
+ return this.#database;
+ }
+
+ get api() {
+ if (this.#api === undefined) {
+ throw new Error("TestContainer > .withApi() must be called before starting the TestContainer.");
+ }
+ return this.#api.client;
+ }
+
+ get authorize() {
+ if (this.#api === undefined) {
+ throw new Error("TestContainer > .withApi() must be called before starting the TestContainer.");
+ }
+ return this.#api.authorize.bind(this.#api);
+ }
+
+ get unauthorize() {
+ if (this.#api === undefined) {
+ throw new Error("TestContainer > .withApi() must be called before starting the TestContainer.");
+ }
+ return this.#api.unauthorize.bind(this.#api);
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Builder
+ |--------------------------------------------------------------------------------
+ */
+
+ withMongo(): this {
+ this.#with.mongodb = true;
+ return this;
+ }
+
+ withDatabase(): this {
+ this.#with.database = true;
+ return this;
+ }
+
+ withApi(): this {
+ this.#with.api = true;
+ return this;
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Lifecycle
+ |--------------------------------------------------------------------------------
+ */
+
+ async start(): Promise {
+ const promises: Promise[] = [];
+ if (this.#isNeeded("mongodb") === true) {
+ promises.push(
+ (async () => {
+ this.#mongodb = await MongoTestContainer.start(config.mongodb);
+ if (this.#isNeeded("database") === true) {
+ this.#database = await new DatabaseTestContainer(this.mongodb).start();
+ }
+ })(),
+ );
+ }
+ if (this.#isNeeded("api") === true) {
+ promises.push(
+ (async () => {
+ this.#api = await new ApiTestContainer().start();
+ })(),
+ );
+ }
+ await Promise.all(promises);
+ return this;
+ }
+
+ async stop(): Promise {
+ await this.#api?.stop();
+ await this.#database?.stop();
+ await this.#mongodb?.stop();
+
+ this.#api = undefined;
+ this.#database = undefined;
+ this.#mongodb = undefined;
+
+ return this;
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Helpers
+ |--------------------------------------------------------------------------------
+ */
+
+ #isNeeded(target: keyof With): boolean {
+ if (this.#with[target] !== false) {
+ return true;
+ }
+ for (const key in this.#needs) {
+ if (this.#with[key as keyof With] !== false && this.#needs[key as keyof With].includes(target) === true) {
+ return true;
+ }
+ }
+ return false;
+ }
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Types
+ |--------------------------------------------------------------------------------
+ */
+
+type Needs = Record;
+
+type With = {
+ mongodb: boolean;
+ database: boolean;
+ api: boolean;
+};
diff --git a/api/libraries/testing/describe.ts b/api/libraries/testing/describe.ts
new file mode 100644
index 0000000..622ea84
--- /dev/null
+++ b/api/libraries/testing/describe.ts
@@ -0,0 +1,24 @@
+import * as assertSuite from "@std/assert";
+import * as bddSuite from "@std/testing/bdd";
+
+import type { TestContainer } from "~libraries/testing/containers/test-container.ts";
+
+import { authorize } from "./utilities/account.ts";
+
+export function describe(name: string, runner: TestRunner): (container: TestContainer) => void {
+ return (container: TestContainer) =>
+ bddSuite.describe(name, () => runner(container, bddSuite, assertSuite, { authorize: authorize(container) }));
+}
+
+export type TestRunner = (
+ container: TestContainer,
+ bdd: {
+ [key in keyof typeof bddSuite]: (typeof bddSuite)[key];
+ },
+ assert: {
+ [key in keyof typeof assertSuite]: (typeof assertSuite)[key];
+ },
+ utils: {
+ authorize: ReturnType;
+ },
+) => void;
diff --git a/api/libraries/testing/utilities/account.ts b/api/libraries/testing/utilities/account.ts
new file mode 100644
index 0000000..057cbec
--- /dev/null
+++ b/api/libraries/testing/utilities/account.ts
@@ -0,0 +1,68 @@
+import type { EventData } from "@valkyr/event-store";
+
+import { AccountCreated, AccountEmailAdded } from "~libraries/auth/.generated/events.ts";
+import { Account } from "~libraries/auth/aggregates/account.ts";
+import { Role } from "~libraries/auth/aggregates/role.ts";
+import type { TestContainer } from "~libraries/testing/containers/test-container.ts";
+
+type AuthorizationOptions = {
+ name?: { family?: string; given?: string };
+ email?: Partial>;
+};
+
+/**
+ * Return a function which provides the ability to create a new account which
+ * is authorized and ready to use for testing authorized requests.
+ *
+ * @param container - Container to authorize against.
+ */
+export function authorize(container: TestContainer): AuthorizeFn {
+ return async (data: EventData, { name = {}, email = {} }: AuthorizationOptions = {}) => {
+ const role = await makeRole(data.type).save();
+ const account = await Account.create(data, "test")
+ .addName(name?.family ?? "Doe", name?.given ?? "John", "test")
+ .addEmail({ value: "john.doe@fixture.none", type: "work", primary: true, verified: true, ...email }, "test")
+ .addRole(role.id, "test")
+ .save();
+ await container.authorize(account.id);
+ return account;
+ };
+}
+
+function makeRole(type: "admin" | "consultant" | "organization"): Role {
+ switch (type) {
+ case "admin": {
+ return Role.create(
+ {
+ name: "Admin",
+ permissions: [
+ { resource: "admin", actions: ["create", "update", "delete"] },
+ { resource: "consultant", actions: ["create", "update", "delete"] },
+ { resource: "organization", actions: ["create", "update", "delete"] },
+ ],
+ },
+ "test",
+ );
+ }
+ case "consultant": {
+ return Role.create(
+ {
+ name: "Consultant",
+ permissions: [{ resource: "consultant", actions: ["create", "update", "delete"] }],
+ },
+ "test",
+ );
+ }
+ case "organization": {
+ return Role.create(
+ {
+ name: "Organization",
+ permissions: [{ resource: "organization", actions: ["create", "update", "delete"] }],
+ },
+ "test",
+ );
+ }
+ }
+}
+
+type AuthorizeFn = (data: EventData, optional?: AuthorizationOptions) => Promise;
diff --git a/api/libraries/utilities/dedent.ts b/api/libraries/utilities/dedent.ts
new file mode 100644
index 0000000..e8da0a4
--- /dev/null
+++ b/api/libraries/utilities/dedent.ts
@@ -0,0 +1,62 @@
+/**
+ * Removes excess indentation caused by using multiline template strings.
+ *
+ * Ported from `dedent-js` solution.
+ *
+ * @see https://github.com/MartinKolarik/dedent-js
+ *
+ * @param templateStrings - Template strings to dedent.
+ *
+ * @example
+ * {
+ * nested: {
+ * examples: [
+ * dedent(`
+ * I am 8 spaces off from the beginning of this file.
+ * But I will be 2 spaces based on the trimmed distance
+ * of the first line.
+ * `),
+ * ]
+ * }
+ * }
+ */
+export function dedent(templateStrings: TemplateStringsArray | string, ...values: any[]) {
+ const matches = [];
+ const strings = typeof templateStrings === "string" ? [templateStrings] : templateStrings.slice();
+
+ // Remove trailing whitespace.
+
+ strings[strings.length - 1] = strings[strings.length - 1].replace(/\r?\n([\t ]*)$/, "");
+
+ // Find all line breaks to determine the highest common indentation level.
+
+ for (let i = 0; i < strings.length; i++) {
+ const match = strings[i].match(/\n[\t ]+/g);
+ if (match) {
+ matches.push(...match);
+ }
+ }
+
+ // Remove the common indentation from all strings.
+
+ if (matches.length) {
+ const size = Math.min(...matches.map((value) => value.length - 1));
+ const pattern = new RegExp(`\n[\t ]{${size}}`, "g");
+ for (let i = 0; i < strings.length; i++) {
+ strings[i] = strings[i].replace(pattern, "\n");
+ }
+ }
+
+ // Remove leading whitespace.
+
+ strings[0] = strings[0].replace(/^\r?\n/, "");
+
+ // Perform interpolation.
+
+ let string = strings[0];
+ for (let i = 0; i < values.length; i++) {
+ string += values[i] + strings[i + 1];
+ }
+
+ return string;
+}
diff --git a/api/libraries/utilities/generate.ts b/api/libraries/utilities/generate.ts
new file mode 100644
index 0000000..7920ef2
--- /dev/null
+++ b/api/libraries/utilities/generate.ts
@@ -0,0 +1,41 @@
+/**
+ * Traverse path and look for a `generate.ts` file in each folder found under
+ * the given path. If a `generate.ts` file is found it is imported so its content
+ * is executed.
+ *
+ * @param path - Path to resolve `generate.ts` files.
+ * @param filter - Which folders found under the given path to ignore.
+ */
+export async function generate(path: string, filter: string[] = []): Promise {
+ const generate: string[] = [];
+ for await (const entry of Deno.readDir(path)) {
+ if (entry.isDirectory === true) {
+ const moduleName = path.split("/").pop();
+ if (moduleName === undefined) {
+ continue;
+ }
+ if (filter.length > 0 && filter.includes(moduleName) === false) {
+ continue;
+ }
+ const filePath = `${path}/${entry.name}/.tasks/generate.ts`;
+ if (await hasFile(filePath)) {
+ generate.push(filePath);
+ }
+ }
+ }
+ for (const filePath of generate) {
+ await import(filePath);
+ }
+}
+
+async function hasFile(filePath: string) {
+ try {
+ await Deno.lstat(filePath);
+ } catch (err) {
+ if (!(err instanceof Deno.errors.NotFound)) {
+ throw err;
+ }
+ return false;
+ }
+ return true;
+}
diff --git a/api/modules/auth/routes/authenticate.ts b/api/modules/auth/routes/authenticate.ts
new file mode 100644
index 0000000..92ca136
--- /dev/null
+++ b/api/modules/auth/routes/authenticate.ts
@@ -0,0 +1,5 @@
+import { authenticate } from "@spec/modules/auth/routes/authenticate.ts";
+
+export default authenticate.access("public").handle(async ({ body }) => {
+ console.log({ body });
+});
diff --git a/api/package.json b/api/package.json
new file mode 100644
index 0000000..6adc53b
--- /dev/null
+++ b/api/package.json
@@ -0,0 +1,23 @@
+{
+ "private": true,
+ "scripts": {
+ "start": "deno --allow-all --watch-hmr=routes/ server.ts",
+ "migrate": "deno run --allow-all .tasks/migrate.ts"
+ },
+ "dependencies": {
+ "@felix/bcrypt": "npm:@jsr/felix__bcrypt@1",
+ "@spec/modules": "workspace:*",
+ "@spec/relay": "workspace:*",
+ "@spec/shared": "workspace:*",
+ "@std/cli": "npm:@jsr/std__cli@1",
+ "@std/dotenv": "npm:@jsr/std__dotenv@0.225",
+ "@std/fs": "npm:@jsr/std__fs@1",
+ "@std/path": "npm:@jsr/std__path@1",
+ "@valkyr/auth": "npm:@jsr/valkyr__auth@2",
+ "@valkyr/event-store": "npm:@jsr/valkyr__event-store@2.0.0-beta.5",
+ "@valkyr/inverse": "npm:@jsr/valkyr__inverse@1",
+ "cookie": "1",
+ "mongodb": "6",
+ "zod": "4"
+ }
+}
\ No newline at end of file
diff --git a/api/server.ts b/api/server.ts
new file mode 100644
index 0000000..da850ab
--- /dev/null
+++ b/api/server.ts
@@ -0,0 +1,93 @@
+import { resolve } from "@std/path";
+import cookie from "cookie";
+
+import { auth, type Session } from "~libraries/auth/mod.ts";
+import { logger } from "~libraries/logger/mod.ts";
+import { asyncLocalStorage } from "~libraries/server/mod.ts";
+import { Api, resolveRoutes } from "~libraries/server/mod.ts";
+
+import { config } from "./config.ts";
+
+const MODULES_DIR = resolve(import.meta.dirname!, "modules");
+
+const log = logger.prefix("Server");
+
+/*
+ |--------------------------------------------------------------------------------
+ | Bootstrap
+ |--------------------------------------------------------------------------------
+ */
+
+await import("./tasks/bootstrap.ts");
+
+/*
+ |--------------------------------------------------------------------------------
+ | Service
+ |--------------------------------------------------------------------------------
+ */
+
+const api = new Api(await resolveRoutes(MODULES_DIR));
+
+/*
+ |--------------------------------------------------------------------------------
+ | Server
+ |--------------------------------------------------------------------------------
+ */
+
+Deno.serve(
+ {
+ port: config.port,
+ hostname: config.host,
+ onListen({ port, hostname }) {
+ logger.prefix("Server").info(`Listening at http://${hostname}:${port}`);
+ },
+ },
+ async (request) => {
+ const url = new URL(request.url);
+
+ // ### Session
+
+ let session: Session | undefined;
+
+ const token = cookie.parse(request.headers.get("cookie") ?? "").token;
+ if (token !== undefined) {
+ const resolved = await auth.resolve(token);
+ if (resolved.valid === false) {
+ return new Response(resolved.message, {
+ status: 401,
+ headers: {
+ "set-cookie": cookie.serialize("token", "", config.cookie(0)),
+ },
+ });
+ }
+ session = resolved;
+ }
+
+ // ### Headers
+ // Set the default headers.
+
+ const headers = new Headers();
+
+ // ### Handle
+
+ const ts = performance.now();
+
+ return asyncLocalStorage.run(
+ {
+ session,
+ info: {
+ method: request.url,
+ start: Date.now(),
+ },
+ response: {
+ headers,
+ },
+ },
+ async () => {
+ return api.fetch(request).finally(() => {
+ log.info(`${request.method} ${url.pathname} [${((performance.now() - ts) / 1000).toLocaleString()} seconds]`);
+ });
+ },
+ );
+ },
+);
diff --git a/api/tasks/bootstrap.ts b/api/tasks/bootstrap.ts
new file mode 100644
index 0000000..c1501c0
--- /dev/null
+++ b/api/tasks/bootstrap.ts
@@ -0,0 +1,68 @@
+import { resolve } from "node:path";
+
+import { logger } from "~libraries/logger/mod.ts";
+
+const LIBRARIES_DIR = resolve(import.meta.dirname!, "..", "libraries");
+
+const log = logger.prefix("Bootstrap");
+
+/*
+ |--------------------------------------------------------------------------------
+ | Database
+ |--------------------------------------------------------------------------------
+ */
+
+await import("~libraries/database/tasks/bootstrap.ts");
+
+/*
+ |--------------------------------------------------------------------------------
+ | Packages
+ |--------------------------------------------------------------------------------
+ */
+
+await bootstrap(LIBRARIES_DIR);
+
+/*
+ |--------------------------------------------------------------------------------
+ | Helpers
+ |--------------------------------------------------------------------------------
+ */
+
+/**
+ * Traverse path and look for a `bootstrap.ts` file in each folder found under
+ * the given path. If a `boostrap.ts` file is found it is imported so its content
+ * is executed.
+ *
+ * @param path - Path to resolve `bootstrap.ts` files.
+ */
+export async function bootstrap(path: string): Promise {
+ const bootstrap: { name: string; path: string }[] = [];
+ for await (const entry of Deno.readDir(path)) {
+ if (entry.isDirectory === true) {
+ const moduleName = path.split("/").pop();
+ if (moduleName === undefined) {
+ continue;
+ }
+ const filePath = `${path}/${entry.name}/.tasks/bootstrap.ts`;
+ if (await hasFile(filePath)) {
+ bootstrap.push({ name: entry.name, path: filePath });
+ }
+ }
+ }
+ for (const entry of bootstrap) {
+ log.info(entry.name);
+ await import(entry.path);
+ }
+}
+
+async function hasFile(filePath: string) {
+ try {
+ await Deno.lstat(filePath);
+ } catch (err) {
+ if (!(err instanceof Deno.errors.NotFound)) {
+ throw err;
+ }
+ return false;
+ }
+ return true;
+}
diff --git a/api/tasks/migrate.ts b/api/tasks/migrate.ts
new file mode 100644
index 0000000..d2c6a37
--- /dev/null
+++ b/api/tasks/migrate.ts
@@ -0,0 +1,66 @@
+import { resolve } from "node:path";
+import process from "node:process";
+
+import { exists } from "@std/fs";
+
+import { config } from "~libraries/database/config.ts";
+import { getMongoClient } from "~libraries/database/connection.ts";
+import { container } from "~libraries/database/container.ts";
+import { logger } from "~libraries/logger/mod.ts";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Dependencies
+ |--------------------------------------------------------------------------------
+ */
+
+const client = getMongoClient(config.mongo);
+
+container.set("client", client);
+
+/*
+|--------------------------------------------------------------------------------
+| Migrate
+|--------------------------------------------------------------------------------
+*/
+
+const db = client.db("api:migrations");
+const collection = db.collection("migrations");
+
+const { default: journal } = await import(resolve(import.meta.dirname!, "migrations", "meta", "_journal.json"), {
+ with: { type: "json" },
+});
+
+const migrations =
+ (await collection.findOne({ name: journal.name })) ?? ({ name: journal.name, entries: [] } as MigrationDocument);
+
+for (const entry of journal.entries) {
+ const migrationFileName = `${String(entry.idx).padStart(4, "0")}_${entry.name}.ts`;
+ if (migrations.entries.includes(migrationFileName)) {
+ continue;
+ }
+ const migrationPath = resolve(import.meta.dirname!, "migrations", migrationFileName);
+ if (await exists(migrationPath)) {
+ await import(migrationPath);
+ await collection.updateOne(
+ {
+ name: journal.name,
+ },
+ {
+ $set: { name: journal.name },
+ $push: { entries: migrationFileName }, // Assuming 'entries' is an array
+ },
+ {
+ upsert: true,
+ },
+ );
+ logger.info(`Migrated ${migrationPath}`);
+ }
+}
+
+type MigrationDocument = {
+ name: string;
+ entries: string[];
+};
+
+process.exit(0);
diff --git a/api/tasks/migrations/meta/_journal.json b/api/tasks/migrations/meta/_journal.json
new file mode 100644
index 0000000..e82d343
--- /dev/null
+++ b/api/tasks/migrations/meta/_journal.json
@@ -0,0 +1,4 @@
+{
+ "name": "api",
+ "entries": []
+}
\ No newline at end of file
diff --git a/apps/README.md b/apps/README.md
new file mode 100644
index 0000000..c7782ba
--- /dev/null
+++ b/apps/README.md
@@ -0,0 +1 @@
+# Apps
\ No newline at end of file
diff --git a/apps/react/.gitignore b/apps/react/.gitignore
new file mode 100644
index 0000000..a547bf3
--- /dev/null
+++ b/apps/react/.gitignore
@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
diff --git a/apps/react/.npmrc b/apps/react/.npmrc
new file mode 100644
index 0000000..41583e3
--- /dev/null
+++ b/apps/react/.npmrc
@@ -0,0 +1 @@
+@jsr:registry=https://npm.jsr.io
diff --git a/apps/react/README.md b/apps/react/README.md
new file mode 100644
index 0000000..7959ce4
--- /dev/null
+++ b/apps/react/README.md
@@ -0,0 +1,69 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default tseslint.config([
+ globalIgnores(['dist']),
+ {
+ files: ['**/*.{ts,tsx}'],
+ extends: [
+ // Other configs...
+
+ // Remove tseslint.configs.recommended and replace with this
+ ...tseslint.configs.recommendedTypeChecked,
+ // Alternatively, use this for stricter rules
+ ...tseslint.configs.strictTypeChecked,
+ // Optionally, add this for stylistic rules
+ ...tseslint.configs.stylisticTypeChecked,
+
+ // Other configs...
+ ],
+ languageOptions: {
+ parserOptions: {
+ project: ['./tsconfig.node.json', './tsconfig.app.json'],
+ tsconfigRootDir: import.meta.dirname,
+ },
+ // other options...
+ },
+ },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default tseslint.config([
+ globalIgnores(['dist']),
+ {
+ files: ['**/*.{ts,tsx}'],
+ extends: [
+ // Other configs...
+ // Enable lint rules for React
+ reactX.configs['recommended-typescript'],
+ // Enable lint rules for React DOM
+ reactDom.configs.recommended,
+ ],
+ languageOptions: {
+ parserOptions: {
+ project: ['./tsconfig.node.json', './tsconfig.app.json'],
+ tsconfigRootDir: import.meta.dirname,
+ },
+ // other options...
+ },
+ },
+])
+```
diff --git a/apps/react/index.html b/apps/react/index.html
new file mode 100644
index 0000000..e4b78ea
--- /dev/null
+++ b/apps/react/index.html
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+ Vite + React + TS
+
+
+
+
+
+
diff --git a/apps/react/package.json b/apps/react/package.json
new file mode 100644
index 0000000..5fe6378
--- /dev/null
+++ b/apps/react/package.json
@@ -0,0 +1,34 @@
+{
+ "name": "react",
+ "private": true,
+ "version": "0.0.0",
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "tsc -b && vite build",
+ "lint": "eslint .",
+ "preview": "vite preview"
+ },
+ "dependencies": {
+ "@tanstack/react-query": "5",
+ "@tanstack/react-router": "1",
+ "@valkyr/db": "1",
+ "@valkyr/event-emitter": "npm:@jsr/valkyr__event-emitter@1",
+ "fast-equals": "5",
+ "react": "19",
+ "react-dom": "19"
+ },
+ "devDependencies": {
+ "@eslint/js": "9",
+ "@types/react": "19",
+ "@types/react-dom": "19",
+ "@vitejs/plugin-react": "4",
+ "eslint": "9",
+ "eslint-plugin-react-hooks": "5",
+ "eslint-plugin-react-refresh": "0.4",
+ "globals": "16",
+ "typescript": "5",
+ "typescript-eslint": "8",
+ "vite": "7"
+ }
+}
diff --git a/apps/react/public/vite.svg b/apps/react/public/vite.svg
new file mode 100644
index 0000000..e7b8dfb
--- /dev/null
+++ b/apps/react/public/vite.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/react/src/App.css b/apps/react/src/App.css
new file mode 100644
index 0000000..b9d355d
--- /dev/null
+++ b/apps/react/src/App.css
@@ -0,0 +1,42 @@
+#root {
+ max-width: 1280px;
+ margin: 0 auto;
+ padding: 2rem;
+ text-align: center;
+}
+
+.logo {
+ height: 6em;
+ padding: 1.5em;
+ will-change: filter;
+ transition: filter 300ms;
+}
+.logo:hover {
+ filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+ filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+ from {
+ transform: rotate(0deg);
+ }
+ to {
+ transform: rotate(360deg);
+ }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+ a:nth-of-type(2) .logo {
+ animation: logo-spin infinite 20s linear;
+ }
+}
+
+.card {
+ padding: 2em;
+}
+
+.read-the-docs {
+ color: #888;
+}
diff --git a/apps/react/src/App.tsx b/apps/react/src/App.tsx
new file mode 100644
index 0000000..cfff5c9
--- /dev/null
+++ b/apps/react/src/App.tsx
@@ -0,0 +1,36 @@
+import "./App.css";
+
+import { useState } from "react";
+
+import viteLogo from "/vite.svg";
+
+import reactLogo from "./assets/react.svg";
+import { Session } from "./components/Session.tsx";
+
+function App() {
+ const [count, setCount] = useState(0);
+
+ return (
+ <>
+
+ Vite + React
+
+
+
+ Edit src/App.tsx and save to test HMR
+
+
+ Click on the Vite and React logos to learn more
+ {
+ const init: RequestInit = { method, headers };
+
+ // ### Before Request
+ // If any before request hooks has been defined, we run them here passing in the
+ // request headers for further modification.
+
+ await this.#beforeRequest(headers);
+
+ // ### Content Type
+ // JSON requests are always of the type 'application/json' and this ensures that
+ // we override any custom pre-hook values for 'content-type' when executing the
+ // request via the 'json' method.
+
+ headers.set("content-type", "application/json");
+
+ // ### Body
+
+ if (body !== undefined) {
+ init.body = JSON.stringify(body);
+ }
+
+ // ### Response
+
+ return this.request(`${endpoint}${query}`, init);
+ }
+
+ async data({ method, endpoint, query, body, headers = new Headers() }: RelayInput): Promise {
+ const init: RequestInit = { method, headers };
+
+ // ### Before Request
+ // If any before request hooks has been defined, we run them here passing in the
+ // request headers for further modification.
+
+ await this.#beforeRequest(headers);
+
+ // ### Content Type
+ // For multipart uploads we let the browser set the correct boundaries.
+
+ headers.delete("content-type");
+
+ // ### Body
+
+ const formData = new FormData();
+
+ if (body !== undefined) {
+ for (const key in body) {
+ const entity = body[key];
+ if (entity === undefined) {
+ continue;
+ }
+ if (Array.isArray(entity)) {
+ const isFileArray = entity.length > 0 && entity.every((candidate) => candidate instanceof File);
+ if (isFileArray) {
+ for (const file of entity) {
+ formData.append(key, file, file.name);
+ }
+ } else {
+ formData.append(key, JSON.stringify(entity));
+ }
+ } else {
+ if (entity instanceof File) {
+ formData.append(key, entity, entity.name);
+ } else {
+ formData.append(key, typeof entity === "string" ? entity : JSON.stringify(entity));
+ }
+ }
+ }
+ init.body = formData;
+ }
+
+ // ### Response
+
+ return this.request(`${endpoint}${query}`, init);
+ }
+
+ /**
+ * Send a fetch request using the given fetch options and returns
+ * a relay formatted response.
+ *
+ * @param endpoint - Which endpoint to submit request to.
+ * @param init - Request init details to submit with the request.
+ */
+ async request(endpoint: string, init?: RequestInit): Promise {
+ return this.#toResponse(await fetch(this.getUrl(endpoint), init));
+ }
+
+ /**
+ * Run before request operations.
+ *
+ * @param headers - Headers to pass to hooks.
+ */
+ async #beforeRequest(headers: Headers) {
+ if (this.options.hooks?.beforeRequest !== undefined) {
+ for (const hook of this.options.hooks.beforeRequest) {
+ await hook(headers);
+ }
+ }
+ }
+
+ /**
+ * Convert a fetch response to a compliant relay response.
+ *
+ * @param response - Fetch response to convert.
+ */
+ async #toResponse(response: Response): Promise {
+ const type = response.headers.get("content-type");
+
+ // ### Content Type
+ // Ensure that the server responds with a 'content-type' definition. We should
+ // always expect the server to respond with a type.
+
+ if (type === null) {
+ return {
+ result: "error",
+ headers: response.headers,
+ error: {
+ status: response.status,
+ message: "Missing 'content-type' in header returned from server.",
+ },
+ };
+ }
+
+ // ### Empty Response
+ // If the response comes back with empty response status 204 we simply return a
+ // empty success.
+
+ if (response.status === 204) {
+ return {
+ result: "success",
+ headers: response.headers,
+ data: null,
+ };
+ }
+
+ // ### SCIM
+ // If the 'content-type' is of type 'scim' we need to convert the SCIM compliant
+ // response to a valid relay response.
+
+ if (type === "application/scim+json") {
+ const parsed = await response.json();
+ if (response.status >= 400) {
+ return {
+ result: "error",
+ headers: response.headers,
+ error: {
+ status: response.status,
+ message: parsed.detail,
+ },
+ };
+ }
+ return {
+ result: "success",
+ headers: response.headers,
+ data: parsed,
+ };
+ }
+
+ // ### JSON
+ // If the 'content-type' contains 'json' we treat it as a 'json' compliant response
+ // and attempt to resolve it as such.
+
+ if (type.includes("json") === true) {
+ const parsed = await response.json();
+ if ("data" in parsed) {
+ return {
+ result: "success",
+ headers: response.headers,
+ data: parsed.data,
+ };
+ }
+ if ("error" in parsed) {
+ return {
+ result: "error",
+ headers: response.headers,
+ error: this.#toError(parsed),
+ };
+ }
+ return {
+ result: "error",
+ headers: response.headers,
+ error: {
+ status: response.status,
+ message: "Unsupported 'json' body returned from server, missing 'data' or 'error' key.",
+ },
+ };
+ }
+
+ return {
+ result: "error",
+ headers: response.headers,
+ error: {
+ status: response.status,
+ message: "Unsupported 'content-type' in header returned from server.",
+ },
+ };
+ }
+
+ #toError(candidate: unknown, status: number = 500): ServerErrorType | ServerErrorResponse["error"] {
+ if (assertServerErrorResponse(candidate)) {
+ return ServerError.fromJSON({ type: "relay", ...candidate.error });
+ }
+ if (typeof candidate === "string") {
+ return {
+ status,
+ message: candidate,
+ };
+ }
+ return {
+ status,
+ message: "Unsupported 'error' returned from server.",
+ };
+ }
+}
+
+export type HttpAdapterOptions = {
+ url: string;
+ hooks?: {
+ beforeRequest?: ((headers: Headers) => Promise)[];
+ };
+};
diff --git a/apps/react/src/assets/react.svg b/apps/react/src/assets/react.svg
new file mode 100644
index 0000000..6c87de9
--- /dev/null
+++ b/apps/react/src/assets/react.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/react/src/components/Session.tsx b/apps/react/src/components/Session.tsx
new file mode 100644
index 0000000..efcf127
--- /dev/null
+++ b/apps/react/src/components/Session.tsx
@@ -0,0 +1,9 @@
+import { makeControllerView } from "../libraries/view.ts";
+import { SessionController } from "./session.controller.ts";
+
+export const Session = makeControllerView(SessionController, ({ state: { error } }) => {
+ if (error !== undefined) {
+ return "Failed to fetch session";
+ }
+ return Session OK!;
+});
diff --git a/apps/react/src/components/session.controller.ts b/apps/react/src/components/session.controller.ts
new file mode 100644
index 0000000..9c83254
--- /dev/null
+++ b/apps/react/src/components/session.controller.ts
@@ -0,0 +1,24 @@
+import { Controller } from "../libraries/controller.ts";
+import { api } from "../services/api.ts";
+
+export class SessionController extends Controller<{
+ error?: string;
+}> {
+ async onInit() {
+ await this.getSessionCookie();
+ }
+
+ async getSessionCookie() {
+ const response = await api.auth.authenticate({
+ body: {
+ type: "email",
+ payload: {
+ email: "john.doe@fixture.none",
+ },
+ },
+ });
+ if ("error" in response) {
+ this.setState("error", undefined);
+ }
+ }
+}
diff --git a/apps/react/src/index.css b/apps/react/src/index.css
new file mode 100644
index 0000000..08a3ac9
--- /dev/null
+++ b/apps/react/src/index.css
@@ -0,0 +1,68 @@
+:root {
+ font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
+ line-height: 1.5;
+ font-weight: 400;
+
+ color-scheme: light dark;
+ color: rgba(255, 255, 255, 0.87);
+ background-color: #242424;
+
+ font-synthesis: none;
+ text-rendering: optimizeLegibility;
+ -webkit-font-smoothing: antialiased;
+ -moz-osx-font-smoothing: grayscale;
+}
+
+a {
+ font-weight: 500;
+ color: #646cff;
+ text-decoration: inherit;
+}
+a:hover {
+ color: #535bf2;
+}
+
+body {
+ margin: 0;
+ display: flex;
+ place-items: center;
+ min-width: 320px;
+ min-height: 100vh;
+}
+
+h1 {
+ font-size: 3.2em;
+ line-height: 1.1;
+}
+
+button {
+ border-radius: 8px;
+ border: 1px solid transparent;
+ padding: 0.6em 1.2em;
+ font-size: 1em;
+ font-weight: 500;
+ font-family: inherit;
+ background-color: #1a1a1a;
+ cursor: pointer;
+ transition: border-color 0.25s;
+}
+button:hover {
+ border-color: #646cff;
+}
+button:focus,
+button:focus-visible {
+ outline: 4px auto -webkit-focus-ring-color;
+}
+
+@media (prefers-color-scheme: light) {
+ :root {
+ color: #213547;
+ background-color: #ffffff;
+ }
+ a:hover {
+ color: #747bff;
+ }
+ button {
+ background-color: #f9f9f9;
+ }
+}
diff --git a/apps/react/src/libraries/controller.ts b/apps/react/src/libraries/controller.ts
new file mode 100644
index 0000000..4ab1e7c
--- /dev/null
+++ b/apps/react/src/libraries/controller.ts
@@ -0,0 +1,372 @@
+import type { ChangeEvent, Collection, SubscribeToMany, SubscribeToSingle, SubscriptionOptions } from "@valkyr/db";
+import type { Subscription } from "@valkyr/event-emitter";
+
+import { Debounce } from "./debounce.ts";
+import { ControllerRefs } from "./refs.ts";
+import type { ControllerClass, Empty, ReactComponent, ReservedPropertyMembers, Unknown } from "./types.ts";
+
+export class Controller {
+ state: TState = {} as TState;
+ props: TProps = {} as TProps;
+
+ /**
+ * Stores a list of referenced elements identifies by a unique key.
+ */
+ readonly refs = new ControllerRefs();
+
+ /**
+ * Records of event emitter subscriptions. They are keyed to a subscription name
+ * for easier identification when unsubscribing.
+ */
+ readonly subscriptions = new Map();
+
+ /**
+ * Has the controller fully resolved the .onInit lifecycle method?
+ */
+ #resolved = false;
+
+ /**
+ * Internal debounce instance used to ensure that we aren't triggering state
+ * updates too frequently when updates are happening in quick succession.
+ */
+ #debounce = new Debounce();
+
+ /**
+ * Creates a new controller instance with given default state and pushState
+ * handler method.
+ *
+ * @param state - Default state to assign to controller.
+ * @param pushData - Push data handler method.
+ */
+ constructor(
+ readonly view: ReactComponent,
+ readonly setView: any,
+ ) {
+ this.query = this.query.bind(this);
+ this.subscribe = this.subscribe.bind(this);
+ this.setState = this.setState.bind(this);
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Factories
+ |--------------------------------------------------------------------------------
+ */
+
+ /**
+ * Creates a new controller instance using the given component and setView handler.
+ *
+ * @param component - Component to render.
+ * @param setView - Method to provide a resolved view component.
+ */
+ static make(
+ this: TController,
+ component: ReactComponent,
+ setView: any,
+ ): InstanceType {
+ return new this(component, setView);
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Bootstrap & Teardown
+ |--------------------------------------------------------------------------------
+ */
+
+ async $resolve(props: TProps): Promise {
+ this.props = props;
+ let state: Partial = {};
+ try {
+ if (this.#resolved === false) {
+ state = {
+ ...state,
+ ...((await this.onInit()) ?? {}),
+ };
+ }
+ state = {
+ ...state,
+ ...((await this.onResolve()) ?? {}),
+ };
+ } catch (err) {
+ console.error(err);
+ throw err;
+ }
+ this.#resolved = true;
+ this.setState(state);
+ }
+
+ async $destroy(): Promise {
+ for (const subscription of this.subscriptions.values()) {
+ subscription.unsubscribe();
+ }
+ await this.onDestroy();
+ this.refs.destroy();
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Lifecycle Methods
+ |--------------------------------------------------------------------------------
+ */
+
+ /**
+ * Method runs once per controller view lifecycle. This is where you should
+ * subscribe to and return initial controller state. A component is kept in
+ * loading state until the initial resolve is completed.
+ *
+ * Once the initial resolve is completed the controller will not run the onInit
+ * method again unless the controller is destroyed and re-created.
+ *
+ * @example
+ * ```ts
+ * async onInit() {
+ * return {
+ * foos: this.query(foos, {}, "foos")
+ * }
+ * }
+ * ```
+ */
+ async onInit(): Promise | void> {
+ return {};
+ }
+
+ /**
+ * Method runs every time the controller is resolved. This is where you should
+ * subscribe to and return state that is reflecting changes to the parent view
+ * properties.
+ *
+ * @example
+ * ```ts
+ * async onResolve() {
+ * return {
+ * foos: this.query(foos, { tenantId: this.props.tenantId }, "foos")
+ * }
+ * }
+ * ```
+ */
+ async onResolve(): Promise | void> {
+ return {};
+ }
+
+ /**
+ * Method runs when the controller parent view is destroyed.
+ */
+ async onDestroy(): Promise {}
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Query Methods
+ |--------------------------------------------------------------------------------
+ */
+
+ /**
+ * Executes a query on a given collection and returns the initial result. A
+ * subsequent internal subscription is also created, which automatically updates
+ * the controller state when changes are made to the data in which the query
+ * subscribes.
+ *
+ * @param collection - Collection to query against.
+ * @param query - Query to execute.
+ * @param stateKey - State key to assign the results to, or state handler method.
+ *
+ * @example
+ * ```ts
+ * async onInit() {
+ * return {
+ * foo: await this.query(db.collection("foos"), { limit: 1 }, "foo")
+ * }
+ * }
+ * ```
+ */
+ async query, TSchema = CollectionSchema, TStateKey = keyof TState>(
+ collection: TCollection,
+ query: QuerySingle,
+ next: TStateKey | ((document: TSchema | undefined) => Promise>),
+ ): Promise;
+
+ /**
+ * Executes a query on a given collection and returns the initial result. A
+ * subsequent internal subscription is also created, which automatically updates
+ * the controller state when changes are made to the data in which the query
+ * subscribes.
+ *
+ * @param collection - Collection to query against.
+ * @param query - Query to execute.
+ * @param next - State key to assign the results to, or state handler method.
+ *
+ * @example
+ * ```ts
+ * async onInit() {
+ * return {
+ * foos: await this.query(db.collection("foos"), {}, "foos")
+ * }
+ * }
+ * ```
+ */
+ async query, TSchema = CollectionSchema, TStateKey = keyof TState>(
+ collection: TCollection,
+ query: QueryMany,
+ next:
+ | TStateKey
+ | ((documents: TSchema[], changed: TSchema[], type: ChangeEvent["type"]) => Promise>),
+ ): Promise;
+
+ /**
+ * Executes a query on a given collection and returns the initial result. A
+ * subsequent internal subscription is also created, which automatically updates
+ * the controller state when changes are made to the data in which the query
+ * subscribes.
+ *
+ * @param collection - Collection to query against.
+ * @param query - Query to execute.
+ * @param stateKey - State key to assign the results to, or state handler method.
+ */
+ async query, TSchema = CollectionSchema, TStateKey = keyof TState>(
+ collection: TCollection,
+ query: Query,
+ next: TStateKey | ((...args: any[]) => Promise>),
+ ): Promise {
+ let resolved = false;
+ this.subscriptions.get(collection.name)?.unsubscribe();
+ return new Promise[] | CollectionSchema | undefined>((resolve) => {
+ const { where, ...options } = query;
+ this.subscriptions.set(
+ collection.name,
+ collection.subscribe(where, options, (...args: any[]) => {
+ if (this.#isStateKey(next)) {
+ if (resolved === true) {
+ this.setState(next, args[0]);
+ }
+ } else {
+ (next as any)(...args).then(this.setState);
+ }
+ setTimeout(() => {
+ resolve(args[0]);
+ resolved = true;
+ }, 0);
+ }),
+ );
+ });
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Event Methods
+ |--------------------------------------------------------------------------------
+ */
+
+ /**
+ * Consumes a subscription under a given event key that is unsubscribed
+ * automatically when the controller is unmounted.
+ *
+ * @param key - Unique identifier used to unsusbcribe duplicate subs.
+ * @param sub - Subscription to unsubscribe on controller unmount.
+ */
+ subscribe(key: string, sub: { unsubscribe: () => void }): void {
+ this.subscriptions.get(key)?.unsubscribe();
+ this.subscriptions.set(key, sub);
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | State Methods
+ |--------------------------------------------------------------------------------
+ */
+
+ /**
+ * Updates the state of the controller and triggers a state update via the push
+ * state handler. This method will debounce state updates to prevent excessive
+ * state updates.
+ *
+ * @param key - State key to assign data to.
+ * @param value - State value to assign.
+ */
+ setState(state: Partial): void;
+ setState(key: K): (state: TState[K]) => void;
+ setState(key: K, value: TState[K]): void;
+ setState(...args: [K | TState, TState[K]?]): void | ((state: TState[K]) => void) {
+ const [target, value] = args;
+
+ if (this.#isStateKey(target) && args.length === 1) {
+ return (value: TState[K]) => {
+ this.setState(target, value);
+ };
+ }
+
+ this.state = this.#isStateKey(target)
+ ? {
+ ...this.state,
+ [target]: value,
+ }
+ : {
+ ...this.state,
+ ...(target as Partial),
+ };
+
+ if (this.#resolved === true) {
+ this.#debounce.run(() => {
+ this.setView(
+ this.view({
+ props: this.props,
+ state: this.state,
+ actions: this.toActions(),
+ refs: this.refs,
+ }),
+ );
+ }, 0);
+ }
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Resolvers
+ |--------------------------------------------------------------------------------
+ */
+
+ /**
+ * Returns all the prototype methods defined on the controller as a list of
+ * actions bound to the controller instance to be used in the view.
+ *
+ * @returns List of actions.
+ */
+ toActions(): Omit {
+ const actions: any = {};
+ for (const name of Object.getOwnPropertyNames(this.constructor.prototype)) {
+ if (name !== "constructor" && name !== "resolve") {
+ const action = (this as any)[name];
+ if (typeof action === "function") {
+ actions[name] = action.bind(this);
+ }
+ }
+ }
+ return actions;
+ }
+
+ /*
+ |--------------------------------------------------------------------------------
+ | Utilities
+ |--------------------------------------------------------------------------------
+ */
+
+ #isStateKey(key: unknown): key is keyof TState {
+ return typeof key === "string";
+ }
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Types
+ |--------------------------------------------------------------------------------
+ */
+
+type Query = Where & SubscriptionOptions;
+
+type QuerySingle = Where & SubscribeToSingle;
+
+type QueryMany = Where & SubscribeToMany;
+
+type Where = {
+ where?: Record;
+};
+
+type CollectionSchema = TCollection extends Collection ? TSchema : never;
diff --git a/apps/react/src/libraries/debounce.ts b/apps/react/src/libraries/debounce.ts
new file mode 100644
index 0000000..0aa2893
--- /dev/null
+++ b/apps/react/src/libraries/debounce.ts
@@ -0,0 +1,14 @@
+export class Debounce {
+ #timeout?: number;
+
+ run(fn: (...args: any[]) => void, ms: number): void {
+ this.#clear();
+ this.#timeout = setTimeout(fn, ms);
+ }
+
+ #clear() {
+ if (this.#timeout !== undefined) {
+ clearTimeout(this.#timeout);
+ }
+ }
+}
diff --git a/apps/react/src/libraries/refs.ts b/apps/react/src/libraries/refs.ts
new file mode 100644
index 0000000..5b5b9d1
--- /dev/null
+++ b/apps/react/src/libraries/refs.ts
@@ -0,0 +1,50 @@
+const refs = new Map();
+
+export class ControllerRefs {
+ #refs = new Map();
+
+ #forwarded: string[] = [];
+
+ set(name: string) {
+ return (element: HTMLElement | null) => {
+ if (element !== null) {
+ refs.set(name, element);
+ }
+ };
+ }
+
+ forward(name: string) {
+ return (element: HTMLElement | null) => {
+ if (element !== null) {
+ refs.set(name, element);
+ this.#forwarded.push(name);
+ }
+ };
+ }
+
+ get(name: string) {
+ const element = this.#refs.get(name) ?? refs.get(name);
+ if (element === undefined) {
+ throw new Error(`Reference Exception: ${name} is not defined.`);
+ }
+ return element;
+ }
+
+ async on(name: string, count = 0): Promise {
+ if (count > 20) {
+ return undefined;
+ }
+ const element = this.#refs.get(name) ?? refs.get(name);
+ if (element === undefined) {
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ return this.on(name, count + 1);
+ }
+ return element;
+ }
+
+ destroy() {
+ this.#forwarded.forEach((name) => {
+ refs.delete(name);
+ });
+ }
+}
diff --git a/apps/react/src/libraries/types.ts b/apps/react/src/libraries/types.ts
new file mode 100644
index 0000000..cea0c80
--- /dev/null
+++ b/apps/react/src/libraries/types.ts
@@ -0,0 +1,22 @@
+import React, { type FunctionComponent } from "react";
+
+import { ControllerRefs } from "./refs.ts";
+
+export type ReactComponent = FunctionComponent<{
+ props: TProps;
+ state: InstanceType["state"];
+ actions: Omit, ReservedPropertyMembers>;
+ refs: ControllerRefs;
+ component?: React.FC;
+}>;
+
+export type ControllerClass = {
+ new (state: any, pushState: any): any;
+ make(component: ReactComponent, pushState: any): any;
+};
+
+export type ReservedPropertyMembers = "state" | "pushState" | "init" | "destroy" | "setNext" | "setState" | "toActions";
+
+export type Unknown = Record;
+
+export type Empty = Record;
diff --git a/apps/react/src/libraries/view.ts b/apps/react/src/libraries/view.ts
new file mode 100644
index 0000000..3238c64
--- /dev/null
+++ b/apps/react/src/libraries/view.ts
@@ -0,0 +1,199 @@
+import { deepEqual } from "fast-equals";
+import React, { createElement, type FunctionComponent, memo, type PropsWithChildren, useEffect, useState } from "react";
+
+import type { ControllerClass, ReactComponent, Unknown } from "./types.ts";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Options
+ |--------------------------------------------------------------------------------
+ */
+
+const options: Partial> = {
+ memoize: defaultMemoizeHandler,
+};
+
+/*
+ |--------------------------------------------------------------------------------
+ | Factory
+ |--------------------------------------------------------------------------------
+ */
+
+export function makeControllerView(
+ controller: TController,
+ component: ReactComponent,
+ options?: Partial>,
+): FunctionComponent {
+ const memoize = getMemoizeHandler(options?.memoize);
+ const render = {
+ loading: getLoadingComponent(options),
+ error: getErrorComponent(options),
+ };
+
+ const container: FunctionComponent> = (props: any) => {
+ const { error, view } = useView(controller, component, props);
+ if (view === undefined) {
+ return render.loading(props);
+ }
+ if (error !== undefined) {
+ return render.error({ ...props, error });
+ }
+ return view;
+ };
+
+ container.displayName = component.displayName = options?.name ?? `${controller.name}View`;
+
+ // ### Memoize
+ // By default run component through react memoization using stringify
+ // matching to determine changes to props.
+
+ if (memoize !== false) {
+ return memo(container, memoize);
+ }
+
+ return container;
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Hooks
+ |--------------------------------------------------------------------------------
+ */
+
+function useView(
+ instance: InstanceType | undefined,
+ component: ReactComponent,
+ props: any,
+) {
+ const [view, setView] = useState();
+
+ const error = useController(instance, component, props, setView);
+
+ return { error, view };
+}
+
+function useController(controller: ControllerClass, component: any, props: any, setView: any) {
+ const [instance, setInstance] = useState | undefined>(undefined);
+ const error = useProps(instance, props);
+
+ useEffect(() => {
+ const instance = controller.make(component, setView);
+ setInstance(instance);
+ return () => {
+ instance.$destroy();
+ };
+ }, []);
+
+ return error;
+}
+
+function useProps(controller: InstanceType | undefined, props: any) {
+ const [error, setError] = useState();
+
+ useEffect(() => {
+ if (controller === undefined) {
+ return;
+ }
+ let isMounted = true;
+ controller.$resolve(props).catch((error: Error) => {
+ if (isMounted === true) {
+ setError(error);
+ }
+ });
+ return () => {
+ isMounted = false;
+ };
+ }, [controller, props]);
+
+ return error;
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Components
+ |--------------------------------------------------------------------------------
+ */
+
+export function setLoadingComponent(component: React.FC) {
+ options.loading = component;
+}
+
+function getLoadingComponent({ loading }: Partial> = {}) {
+ const component = loading ?? options.loading;
+ if (component === undefined) {
+ return () => null;
+ }
+ return (props: TProps) => createElement(component, props);
+}
+
+export function setErrorComponent(component: React.FC) {
+ options.error = component;
+}
+
+function getErrorComponent({ error }: Partial> = {}) {
+ const component = error ?? options.loading;
+ if (component === undefined) {
+ return () => null;
+ }
+ return (props: TProps) => createElement(component, props);
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Memoize
+ |--------------------------------------------------------------------------------
+ */
+
+export function setMemoizeHandler(value: boolean | Memoize) {
+ if (typeof value === "function") {
+ options.memoize = value;
+ } else if (value === false) {
+ options.memoize = false;
+ } else {
+ options.memoize = defaultMemoizeHandler;
+ }
+}
+
+function getMemoizeHandler(memoize?: ViewOptions["memoize"]): false | Memoize | undefined {
+ if (typeof memoize === "function") {
+ return memoize;
+ }
+ if (memoize !== false) {
+ return options.memoize;
+ }
+ return false;
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Defaults
+ |--------------------------------------------------------------------------------
+ */
+
+function defaultMemoizeHandler(prev: any, next: any): boolean {
+ if (prev.children !== undefined && next.children !== undefined) {
+ if (prev.children.type.type.displayName !== next.children.type.type.displayName) {
+ return false;
+ }
+ }
+ return deepEqual(prev, next);
+}
+
+/*
+ |--------------------------------------------------------------------------------
+ | Types
+ |--------------------------------------------------------------------------------
+ */
+
+export type ViewOptions = {
+ name?: string;
+ loading: React.FC;
+ error: React.FC;
+ memoize: false | Memoize;
+};
+
+type Memoize = (prevProps: Readonly, nextProps: Readonly) => boolean;
+
+type Readonly = {
+ readonly [P in keyof T]: T[P];
+};
diff --git a/apps/react/src/main.tsx b/apps/react/src/main.tsx
new file mode 100644
index 0000000..33bb9dd
--- /dev/null
+++ b/apps/react/src/main.tsx
@@ -0,0 +1,26 @@
+import "./index.css";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createRouter, RouterProvider } from "@tanstack/react-router";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+import { routeTree } from "./routes.tsx";
+
+const queryClient = new QueryClient();
+
+const router = createRouter({ routeTree });
+
+declare module "@tanstack/react-router" {
+ interface Register {
+ router: typeof router;
+ }
+}
+
+createRoot(document.getElementById("root")!).render(
+
+
+
+ ,
+);
diff --git a/apps/react/src/routes.tsx b/apps/react/src/routes.tsx
new file mode 100644
index 0000000..a3356be
--- /dev/null
+++ b/apps/react/src/routes.tsx
@@ -0,0 +1,9 @@
+import { createRootRoute } from "@tanstack/react-router";
+
+import App from "./App.tsx";
+
+const rootRoute = createRootRoute({
+ component: App,
+});
+
+export const routeTree = rootRoute.addChildren([]);
diff --git a/apps/react/src/services/api.ts b/apps/react/src/services/api.ts
new file mode 100644
index 0000000..197b702
--- /dev/null
+++ b/apps/react/src/services/api.ts
@@ -0,0 +1,14 @@
+import { makeClient } from "@spec/relay";
+
+import { HttpAdapter } from "../adapters/http.ts";
+
+export const api = makeClient(
+ {
+ adapter: new HttpAdapter({
+ url: window.location.origin,
+ }),
+ },
+ {
+ auth: (await import("@spec/modules/auth/mod.ts")).routes,
+ },
+);
diff --git a/apps/react/src/vite-env.d.ts b/apps/react/src/vite-env.d.ts
new file mode 100644
index 0000000..11f02fe
--- /dev/null
+++ b/apps/react/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// {
- constructor(readonly state: TActionState) {}
-
- /**
- * Input object required by the action to fulfill its function.
- *
- * @param input - Schema defining the input requirements of the action.
- */
- input(input: TInput): Action & { input: TInput }> {
- return new Action({ ...this.state, input });
- }
-
- /**
- * Output object defining the result shape of the action.
- *
- * @param output - Schema defining the result shape.
- */
- output(output: TOutput): Action & { output: ZodObject }> {
- return new Action({ ...this.state, output: z.object(output) as any });
- }
-
- /**
- * Add handler method to the action.
- *
- * @param handle - Handler method.
- */
- handle>(
- handle: THandleFn,
- ): Action & { handle: THandleFn }> {
- return new Action({ ...this.state, handle });
- }
-}
-
-/*
- |--------------------------------------------------------------------------------
- | Factory
- |--------------------------------------------------------------------------------
- */
-
-export const action: {
- make(name: string): Action;
-} = {
- make(name: string) {
- return new Action({ name });
- },
-};
-
-/*
- |--------------------------------------------------------------------------------
- | Types
- |--------------------------------------------------------------------------------
- */
-
-type ActionState = {
- name: string;
- input?: ZodType;
- output?: ZodObject;
- handle?: ActionHandlerFn;
-};
-
-export type ActionPrepareFn = (
- params: z.infer,
-) => TAction["state"]["input"] extends ZodType ? z.infer : void;
-
-type ActionHandlerFn = TInput extends ZodType
- ? (input: z.infer) => TOutput extends ZodObject ? Promise | RelayError> : Promise
- : () => TOutput extends ZodObject ? Promise | RelayError> : Promise;
diff --git a/libraries/adapter.ts b/libraries/adapter.ts
deleted file mode 100644
index 1c606a8..0000000
--- a/libraries/adapter.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { RelayError } from "./errors.ts";
-import type { RouteMethod } from "./route.ts";
-
-export type RelayAdapter = {
- readonly url: string;
- fetch(input: RelayRESTInput): Promise;
- send(input: RelayProcedureInput): Promise;
-};
-
-export type RelayRESTInput = {
- method: RouteMethod;
- url: string;
- query?: string;
- body?: string;
-};
-
-export type RelayProcedureInput = {
- method: string;
- params: any;
-};
-
-export type RelayProcedureResponse =
- | {
- relay: "1.0";
- result: unknown;
- id: string | number;
- }
- | {
- relay: "1.0";
- error: RelayError;
- id: string | number;
- };
diff --git a/libraries/api.ts b/libraries/api.ts
deleted file mode 100644
index c0975ac..0000000
--- a/libraries/api.ts
+++ /dev/null
@@ -1,434 +0,0 @@
-import z from "zod";
-
-import { BadRequestError, InternalServerError, NotFoundError, RelayError } from "./errors.ts";
-import { Procedure } from "./procedure.ts";
-import { RelayRequest, request } from "./request.ts";
-import { Route, RouteMethod } from "./route.ts";
-
-const SUPPORTED_MEHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
-
-export class Api {
- readonly #index = {
- rest: new Map(),
- rpc: new Map(),
- };
-
- /**
- * Route maps funneling registered routes to the specific methods supported by
- * the relay instance.
- */
- readonly routes: Routes = {
- POST: [],
- GET: [],
- PUT: [],
- PATCH: [],
- DELETE: [],
- };
-
- /**
- * List of paths in the '${method} ${path}' format allowing us to quickly throw
- * errors if a duplicate route path is being added.
- */
- readonly #paths = new Set();
-
- /**
- * Instantiate a new Server instance.
- *
- * @param routes - Routes to register with the instance.
- */
- constructor(relays: TRelays) {
- const methods: (keyof typeof this.routes)[] = [];
- for (const relay of relays) {
- if (relay instanceof Procedure === true) {
- this.#index.rpc.set(relay.method, relay);
- }
- if (relay instanceof Route === true) {
- this.#validateRoutePath(relay);
- this.routes[relay.method].push(relay);
- methods.push(relay.method);
- this.#index.rest.set(`${relay.method} ${relay.path}`, relay);
- }
- }
- for (const method of methods) {
- this.routes[method].sort(byStaticPriority);
- }
- }
-
- /**
- * Takes a request candidate and parses its json body.
- *
- * @param candidate - Request candidate to parse.
- */
- async parse(candidate: Request): Promise {
- return request.parseAsync(await candidate.json());
- }
-
- /**
- * Handle a incoming REST request.
- *
- * @param request - REST request to pass to a route handler.
- */
- async rest(request: Request): Promise {
- const url = new URL(request.url);
-
- const matched = this.#resolve(request.method, request.url);
- if (matched === undefined) {
- return toRestResponse(
- new NotFoundError(`Invalid routing path provided for ${request.url}`, {
- method: request.method,
- url: request.url,
- }),
- );
- }
-
- const { route, params } = matched;
-
- // ### Context
- // Context is passed to every route handler and provides a suite of functionality
- // and request data.
-
- const context: any[] = [];
-
- // ### Params
- // If the route has params we want to coerce the values to the expected types.
-
- if (route.state.params !== undefined) {
- const result = await route.state.params.safeParseAsync(params);
- if (result.success === false) {
- return toRestResponse(new BadRequestError("Invalid request params", z.prettifyError(result.error)));
- }
- context.push(result.data);
- }
-
- // ### Query
- // If the route has a query schema we need to validate and parse the query.
-
- if (route.state.query !== undefined) {
- const result = await route.state.query.safeParseAsync(toQuery(url.searchParams) ?? {});
- if (result.success === false) {
- return toRestResponse(new BadRequestError("Invalid request query", z.prettifyError(result.error)));
- }
- context.push(result.data);
- }
-
- // ### Body
- // If the route has a body schema we need to validate and parse the body.
-
- if (route.state.body !== undefined) {
- let body: Record = {};
- if (request.headers.get("content-type")?.includes("json")) {
- body = await request.json();
- }
- const result = await route.state.body.safeParseAsync(body);
- if (result.success === false) {
- return toRestResponse(new BadRequestError("Invalid request body", z.prettifyError(result.error)));
- }
- context.push(result.data);
- }
-
- // ### Actions
- // Run through all assigned actions for the route.
-
- const data: Record = {};
-
- if (route.state.actions !== undefined) {
- for (const entry of route.state.actions) {
- let action = entry;
- let input: any;
-
- if (Array.isArray(entry)) {
- action = entry[0];
- input = entry[1](...context);
- }
-
- const result = (await action.state.input?.safeParseAsync(input)) ?? { success: true, data: {} };
- if (result.success === false) {
- return toRestResponse(new BadRequestError("Invalid action input", z.prettifyError(result.error)));
- }
-
- if (action.state.handle === undefined) {
- return toRestResponse(new InternalServerError(`Action '${action.state.name}' is missing handler.`));
- }
-
- const output = await action.state.handle(result.data);
- if (output instanceof RelayError) {
- return toRestResponse(output);
- }
-
- for (const key in output) {
- data[key] = output[key];
- }
- }
- context.push(data);
- }
-
- // ### Handler
- // Execute the route handler and apply the result.
-
- if (route.state.handle === undefined) {
- return toRestResponse(new InternalServerError(`Path '${route.method} ${route.path}' is missing request handler.`));
- }
- return toRestResponse(await route.state.handle(...context).catch((error) => error));
- }
-
- /**
- * Handle a incoming RPC request.
- *
- * @param method - Method name being executed.
- * @param params - Parameters provided with the method request.
- * @param id - Request id used for response identification.
- */
- async rpc({ method, params, id }: RelayRequest): Promise {
- const procedure = this.#index.rpc.get(method);
- if (procedure === undefined) {
- return toResponse(new NotFoundError(`Method '' does not exist`), id);
- }
-
- // ### Context
- // Context is passed to every route handler and provides a suite of functionality
- // and request data.
-
- const args: any[] = [];
-
- // ### Params
- // If the route has a body schema we need to validate and parse the body.
-
- if (procedure.state.params !== undefined) {
- if (params === undefined) {
- return toResponse(new BadRequestError("Procedure expected 'params' but got 'undefined'."), id);
- }
- const result = await procedure.state.params.safeParseAsync(params);
- if (result.success === false) {
- return toResponse(new BadRequestError("Invalid request body", z.prettifyError(result.error)), id);
- }
- args.push(result.data);
- }
-
- // ### Actions
- // Run through all assigned actions for the route.
-
- const data: Record = {};
-
- if (procedure.state.actions !== undefined) {
- for (const entry of procedure.state.actions) {
- let action = entry;
- let input: any;
-
- if (Array.isArray(entry)) {
- action = entry[0];
- input = entry[1](args[0]);
- }
-
- const result = (await action.state.input?.safeParseAsync(input)) ?? { success: true, data: {} };
- if (result.success === false) {
- return toResponse(new BadRequestError("Invalid action input", z.prettifyError(result.error)), id);
- }
-
- if (action.state.handle === undefined) {
- return toResponse(new InternalServerError(`Action '${action.state.name}' is missing handler.`), id);
- }
-
- const output = await action.state.handle(result.data);
- if (output instanceof RelayError) {
- return toResponse(output, id);
- }
-
- for (const key in output) {
- data[key] = output[key];
- }
- }
- args.push(data);
- }
-
- // ### Handler
- // Execute the route handler and apply the result.
-
- if (procedure.state.handle === undefined) {
- return toResponse(new InternalServerError(`Path '${procedure.method}' is missing request handler.`), id);
- }
- return toResponse(await procedure.state.handle(...args).catch((error) => error), id);
- }
-
- /**
- * Attempt to resolve a route based on the given method and pathname.
- *
- * @param method - HTTP method.
- * @param url - HTTP request url.
- */
- #resolve(method: string, url: string): ResolvedRoute | undefined {
- this.#assertMethod(method);
- for (const route of this.routes[method]) {
- if (route.match(url) === true) {
- return { route, params: route.getParsedParams(url) };
- }
- }
- }
-
- #validateRoutePath(route: Route): void {
- const path = `${route.method} ${route.path}`;
- if (this.#paths.has(path)) {
- throw new Error(`Router > Path ${path} already exists`);
- }
- this.#paths.add(path);
- }
-
- #assertMethod(method: string): asserts method is RouteMethod {
- if (!SUPPORTED_MEHODS.includes(method)) {
- throw new Error(`Router > Unsupported method '${method}'`);
- }
- }
-}
-
-/*
- |--------------------------------------------------------------------------------
- | Helpers
- |--------------------------------------------------------------------------------
- */
-
-/**
- * Sorting method for routes to ensure that static properties takes precedence
- * for when a route is matched against incoming requests.
- *
- * @param a - Route A
- * @param b - Route B
- */
-function byStaticPriority(a: Route, b: Route) {
- const aSegments = a.path.split("/");
- const bSegments = b.path.split("/");
-
- const maxLength = Math.max(aSegments.length, bSegments.length);
-
- for (let i = 0; i < maxLength; i++) {
- const aSegment = aSegments[i] || "";
- const bSegment = bSegments[i] || "";
-
- const isADynamic = aSegment.startsWith(":");
- const isBDynamic = bSegment.startsWith(":");
-
- if (isADynamic !== isBDynamic) {
- return isADynamic ? 1 : -1;
- }
-
- if (isADynamic === false && aSegment !== bSegment) {
- return aSegment.localeCompare(bSegment);
- }
- }
-
- return a.path.localeCompare(b.path);
-}
-
-/**
- * Resolve and return query object from the provided search parameters, or undefined
- * if the search parameters does not have any entries.
- *
- * @param searchParams - Search params to create a query object from.
- */
-function toQuery(searchParams: URLSearchParams): object | undefined {
- if (searchParams.size === 0) {
- return undefined;
- }
- const result: Record = {};
- for (const [key, value] of searchParams.entries()) {
- result[key] = value;
- }
- return result;
-}
-
-/**
- * Takes a server side request result and returns a fetch Response.
- *
- * @param result - Result to send back as a Response.
- */
-function toRestResponse(result: object | RelayError | Response | void): Response {
- if (result instanceof Response) {
- return result;
- }
- if (result instanceof RelayError) {
- return new Response(result.message, {
- status: result.status,
- });
- }
- if (result === undefined) {
- return new Response(null, { status: 204 });
- }
- return new Response(JSON.stringify(result), {
- status: 200,
- headers: {
- "content-type": "application/json",
- },
- });
-}
-
-/**
- * Takes a server side request result and returns a fetch Response.
- *
- * @param result - Result to send back as a Response.
- * @param id - Request id which can be used to identify the response.
- */
-export function toResponse(result: object | RelayError | Response | void, id: string | number): Response {
- if (result === undefined) {
- return new Response(
- JSON.stringify({
- relay: "1.0",
- result: null,
- id,
- }),
- {
- status: 200,
- headers: {
- "content-type": "application/json",
- },
- },
- );
- }
- if (result instanceof Response) {
- return result;
- }
- if (result instanceof RelayError) {
- return new Response(
- JSON.stringify({
- relay: "1.0",
- error: result,
- id,
- }),
- {
- status: result.status,
- headers: {
- "content-type": "application/json",
- },
- },
- );
- }
- return new Response(
- JSON.stringify({
- relay: "1.0",
- result,
- id,
- }),
- {
- status: 200,
- headers: {
- "content-type": "application/json",
- },
- },
- );
-}
-
-/*
- |--------------------------------------------------------------------------------
- | Types
- |--------------------------------------------------------------------------------
- */
-
-type Routes = {
- POST: Route[];
- GET: Route[];
- PUT: Route[];
- PATCH: Route[];
- DELETE: Route[];
-};
-
-type ResolvedRoute = {
- route: Route;
- params: any;
-};
diff --git a/libraries/client.ts b/libraries/client.ts
deleted file mode 100644
index 3700eb7..0000000
--- a/libraries/client.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-import z, { ZodType } from "zod";
-
-import type { RelayAdapter, RelayRESTInput } from "./adapter.ts";
-import { Procedure } from "./procedure.ts";
-import type { Relays } from "./relay.ts";
-import { Route } from "./route.ts";
-
-/**
- * Make a new relay client instance.
- *
- * @param config - Client configuration.
- * @param procedures - Map of procedures to make available to the client.
- */
-export function makeRelayClient(config: RelayClientConfig, relays: TRelays): RelayClient {
- return mapRelays(relays, config.adapter);
-}
-
-/*
- |--------------------------------------------------------------------------------
- | Helpers
- |--------------------------------------------------------------------------------
- */
-
-function mapRelays(relays: TRelays, adapter: RelayAdapter): RelayClient {
- const client: any = {};
- for (const key in relays) {
- const relay = relays[key];
- if (relay instanceof Procedure) {
- client[key] = async (params: unknown) => {
- const response = await adapter.send({ method: relay.method, params });
- if ("error" in response) {
- throw new Error(response.error.message);
- }
- if ("result" in response && relay.state.result !== undefined) {
- return relay.state.result.parseAsync(response.result);
- }
- return response.result;
- };
- } else if (relay instanceof Route) {
- client[key] = async (...args: any[]) => {
- const input: RelayRESTInput = { method: relay.state.method, url: `${adapter.url}${relay.state.path}`, query: "" };
-
- let index = 0; // argument incrementor
-
- if (relay.state.params !== undefined) {
- const params = args[index++] as { [key: string]: string };
- for (const key in params) {
- input.url = input.url.replace(`:${key}`, params[key]);
- }
- }
-
- if (relay.state.query !== undefined) {
- const query = args[index++] as { [key: string]: string };
- const pieces: string[] = [];
- for (const key in query) {
- pieces.push(`${key}=${query[key]}`);
- }
- if (pieces.length > 0) {
- input.query = `?${pieces.join("&")}`;
- }
- }
-
- if (relay.state.body !== undefined) {
- input.body = JSON.stringify(args[index++]);
- }
-
- // ### Fetch
-
- const data = await adapter.fetch(input);
- if (relay.state.output !== undefined) {
- return relay.state.output.parse(data);
- }
- return data;
- };
- } else {
- client[key] = mapRelays(relay, adapter);
- }
- }
- return client;
-}
-
-/*
- |--------------------------------------------------------------------------------
- | Types
- |--------------------------------------------------------------------------------
- */
-
-export type RelayClient = {
- [TKey in keyof TRelays]: TRelays[TKey] extends Procedure
- ? TState["params"] extends ZodType
- ? (params: z.infer) => Promise : void>
- : () => Promise : void>
- : TRelays[TKey] extends Route
- ? (...args: TRelays[TKey]["args"]) => Promise>
- : TRelays[TKey] extends Relays
- ? RelayClient
- : never;
-};
-
-type RelayRouteResponse = TRoute["state"]["output"] extends ZodType ? z.infer : void;
-
-export type RelayClientConfig = {
- adapter: RelayAdapter;
-};
diff --git a/libraries/procedure.ts b/libraries/procedure.ts
deleted file mode 100644
index 268fd36..0000000
--- a/libraries/procedure.ts
+++ /dev/null
@@ -1,153 +0,0 @@
-import z, { ZodObject, ZodType } from "zod";
-
-import { Action } from "./action.ts";
-import { RelayError } from "./errors.ts";
-
-export class Procedure {
- readonly type = "rpc" as const;
-
- declare readonly args: Args;
-
- constructor(readonly state: TState) {}
-
- get method(): TState["method"] {
- return this.state.method;
- }
-
- /**
- * Params allows for custom casting of URL parameters. If a parameter does not
- * have a corresponding zod schema the default param type is "string".
- *
- * @param params - URL params.
- *
- * @examples
- *
- * ```ts
- * relay
- * .method("user:create")
- * .params(
- * z.object({
- * bar: z.number()
- * })
- * )
- * .handle(async ({ bar }) => {
- * console.log(typeof bar); // => number
- * });
- * ```
- */
- params(params: TParams): Procedure & { params: TParams }> {
- return new Procedure({ ...this.state, params });
- }
-
- /**
- * List of route level middleware action to execute before running the
- * route handler.
- *
- * @param actions - Actions to execute on this route.
- *
- * @examples
- *
- * ```ts
- * const hasFooBar = action
- * .make("hasFooBar")
- * .output(z.object({ foobar: z.number() }))
- * .handle(async () => {
- * return {
- * foobar: 1,
- * };
- * });
- *
- * relay
- * .method("foo")
- * .actions([hasFooBar])
- * .handle(async ({ foobar }) => {
- * console.log(typeof foobar); // => number
- * });
- * ```
- */
- actions>(
- actions: (TAction | [TAction, TActionFn])[],
- ): Procedure & { actions: TAction[] }> {
- return new Procedure({ ...this.state, actions: actions as TAction[] });
- }
-
- /**
- * Shape of the response this route produces. This is used by the transform
- * tools to ensure the client receives parsed data.
- *
- * @param response - Response shape of the route.
- *
- * @examples
- *
- * ```ts
- * relay
- * .method("foo")
- * .result(
- * z.object({
- * bar: z.number()
- * })
- * )
- * .handle(async () => {
- * return { bar: 1 };
- * });
- * ```
- */
- result(result: TResult): Procedure & { result: TResult }> {
- return new Procedure({ ...this.state, result });
- }
-
- /**
- * Server handler callback method.
- *
- * @param handle - Handle function to trigger when the route is executed.
- */
- handle>(handle: THandleFn): Procedure & { handle: THandleFn }> {
- return new Procedure({ ...this.state, handle });
- }
-}
-
-/*
- |--------------------------------------------------------------------------------
- | Factories
- |--------------------------------------------------------------------------------
- */
-
-export const rpc: {
- method(method: TMethod): Procedure<{ type: "rpc"; method: TMethod }>;
-} = {
- method(method: TMethod): Procedure<{ type: "rpc"; method: TMethod }> {
- return new Procedure({ type: "rpc", method });
- },
-};
-
-/*
- |--------------------------------------------------------------------------------
- | Types
- |--------------------------------------------------------------------------------
- */
-
-type State = {
- method: string;
- params?: ZodType;
- actions?: Array;
- result?: ZodType;
- handle?: HandleFn;
-};
-
-type ActionFn = TState["params"] extends ZodType
- ? (params: z.infer) => TAction["state"]["input"] extends ZodType ? z.infer : void
- : () => TAction["state"]["input"] extends ZodType ? z.infer : void;
-
-type HandleFn = any[], TResponse = any> = (
- ...args: TArgs
-) => TResponse extends ZodType ? Promise | Response | RelayError> : Promise;
-
-type Args = [
- ...(TState["params"] extends ZodType ? [z.infer] : []),
- ...(TState["actions"] extends Array ? [UnionToIntersection>] : []),
-];
-
-type MergeAction> =
- TActions[number] extends Action ? (TState["output"] extends ZodObject ? z.infer : object) : object;
-
-type UnionToIntersection = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
diff --git a/libraries/relay.ts b/libraries/relay.ts
deleted file mode 100644
index dcb5f24..0000000
--- a/libraries/relay.ts
+++ /dev/null
@@ -1,158 +0,0 @@
-import { Api } from "./api.ts";
-import { makeRelayClient, RelayClient, RelayClientConfig } from "./client.ts";
-import { Procedure } from "./procedure.ts";
-import { Route, RouteMethod } from "./route.ts";
-
-export class Relay<
- TRelays extends Relays,
- TRPCIndex = RPCIndex,
- TPostIndex = RouteIndex<"POST", TRelays>,
- TGetIndex = RouteIndex<"GET", TRelays>,
- TPutIndex = RouteIndex<"PUT", TRelays>,
- TPatchIndex = RouteIndex<"PATCH", TRelays>,
- TDeleteIndex = RouteIndex<"DELETE", TRelays>,
-> {
- readonly #index = new Map();
-
- declare readonly $inferClient: RelayClient;
-
- /**
- * Instantiate a new Relay instance.
- *
- * @param procedures - Procedures to register with the instance.
- */
- constructor(readonly relays: TRelays) {
- indexRelays(relays, this.#index);
- }
-
- /**
- * Create a new relay api instance with the given relays.
- *
- * @param relays - List of relays to handle.
- */
- api(relays: TRelays): Api {
- return new Api(relays);
- }
-
- /**
- * Create a new relay client instance from the instance procedures.
- *
- * @param config - Client configuration.
- */
- client(config: RelayClientConfig): this["$inferClient"] {
- return makeRelayClient(config, this.relays) as any;
- }
-
- /**
- * Retrieve a registered procedure registered with the relay instance.
- *
- * @param method - Method name assigned to the procedure.
- */
- method(method: TMethod): TRPCIndex[TMethod] {
- return this.#index.get(method as string) as TRPCIndex[TMethod];
- }
-
- /**
- * Retrieve a registered 'POST' route registered with the relay instance.
- *
- * @param path - Route path to retrieve.
- */
- post(path: TPath): TPostIndex[TPath] {
- return this.#index.get(`POST ${path as string}`) as TPostIndex[TPath];
- }
-
- /**
- * Retrieve a registered 'GET' route registered with the relay instance.
- *
- * @param path - Route path to retrieve.
- */
- get(path: TPath): TGetIndex[TPath] {
- return this.#index.get(`GET ${path as string}`) as TGetIndex[TPath];
- }
-
- /**
- * Retrieve a registered 'PUT' route registered with the relay instance.
- *
- * @param path - Route path to retrieve.
- */
- put(path: TPath): TPutIndex[TPath] {
- return this.#index.get(`PUT ${path as string}`) as TPutIndex[TPath];
- }
-
- /**
- * Retrieve a registered 'PATCH' route registered with the relay instance.
- *
- * @param path - Route path to retrieve.
- */
- patch(path: TPath): TPatchIndex[TPath] {
- return this.#index.get(`PATCH ${path as string}`) as TPatchIndex[TPath];
- }
-
- /**
- * Retrieve a registered 'DELETE' route registered with the relay instance.
- *
- * @param path - Route path to retrieve.
- */
- delete(path: TPath): TDeleteIndex[TPath] {
- return this.#index.get(`DELETE ${path as string}`) as TDeleteIndex[TPath];
- }
-}
-
-/*
- |--------------------------------------------------------------------------------
- | Helpers
- |--------------------------------------------------------------------------------
- */
-
-function indexRelays(relays: Relays, index: Map) {
- for (const key in relays) {
- const relay = relays[key];
- if (relay instanceof Procedure) {
- const method = relay.method;
- if (index.has(method)) {
- throw new Error(`Relay > Procedure with method '${method}' already exists!`);
- }
- index.set(method, relay);
- } else if (relay instanceof Route) {
- const path = `${relay.method} ${relay.path}`;
- if (index.has(path)) {
- throw new Error(`Relay > Procedure with path 'path' already exists!`);
- }
- index.set(path, relay);
- } else {
- indexRelays(relay, index);
- }
- }
-}
-
-/*
- |--------------------------------------------------------------------------------
- | Types
- |--------------------------------------------------------------------------------
- */
-
-export type Relays = {
- [key: string]: Relays | Procedure | Route;
-};
-
-type RPCIndex = MergeUnion>;
-
-type RouteIndex = MergeUnion>;
-
-type FlattenRPCRelays = {
- [TKey in keyof TRelays]: TRelays[TKey] extends Procedure
- ? Record
- : TRelays[TKey] extends Relays
- ? FlattenRPCRelays
- : never;
-}[keyof TRelays];
-
-type FlattenRouteRelays = {
- [TKey in keyof TRelays]: TRelays[TKey] extends { state: { method: TMethod; path: infer TPath extends string } }
- ? Record