appos 0.3.5-0 → 0.3.6-0

package/dist/exports/api/database.mjs

@@ -1,219 +0,0 @@
-import { APPOS_DIR, DATABASES_DIR } from "./constants.mjs";
-import { getTableName, sql } from "drizzle-orm";
-import { join } from "node:path";
-import { drizzle } from "drizzle-orm/node-postgres";
-import { migrate } from "drizzle-orm/node-postgres/migrator";
-import pg from "pg";
-
-//#region src/api/database.ts
-const { Client, Pool: Pool$1 } = pg;
-/**
-* The schema used for migrations.
-*/
-const migrationsSchema = "public";
-/**
-* Get the migration options for a specific database.
-*
-* @param name Name of the database to get migration options for
-* @param type Type of migration (schema or data), defaults to "schema"
-* @returns Migration configuration for drizzle-orm
-*/
-function defineMigrationOpts(name, type = "schema") {
-	const folder = type === "schema" ? "schema-migrations" : "data-migrations";
-	const table = type === "schema" ? "schema-migrations" : "data-migrations";
-	return {
-		migrationsFolder: `${join(APPOS_DIR, DATABASES_DIR)}/${name}/${folder}`,
-		migrationsSchema,
-		migrationsTable: table
-	};
-}
-/**
-* The database logger.
-*/
-var DatabaseLogger = class {
-	#logger;
-	constructor(logger) {
-		this.#logger = logger;
-	}
-	logQuery(query, params) {
-		this.#logger.info(params, query);
-	}
-};
-/**
-* Generate old and new row JSONB representations for delete/insert/update queries.
-* Uses PostgreSQL 18's OLD/NEW support in RETURNING clause.
-*
-* @param table The table to generate changes for.
-* @returns Object containing `_table`, `old` and `new` JSONB columns.
-*/
-function dbChanges(table) {
-	const tableName = getTableName(table);
-	return {
-		_table: sql`${sql.raw(`'${tableName}'`)}`.as("_table"),
-		old: sql`to_jsonb(OLD.*)`.as("old"),
-		new: sql`to_jsonb(NEW.*)`.as("new")
-	};
-}
-/**
-* Define the database with the provided options.
-*
-* Algorithm:
-* 1. Create a connection pool with sensible defaults
-* 2. Initialize drizzle ORM with schema and relations
-*
-* @param opts The options for defining the database, including pool configuration, relations, and schema.
-* @template TSchema The schema type for the database.
-* @template TRelations The relations type for the database.
-* @returns The defined database instance.
-*/
-async function defineDatabase(opts) {
-	return drizzle({
-		client: new Pool$1({
-			application_name: "appos",
-			max: 16,
-			...opts.poolConfig
-		}),
-		logger: new DatabaseLogger(opts.logger),
-		relations: opts.relations,
-		schema: opts.schema
-	});
-}
-/**
-* Create a single test database with isolated schema.
-*
-* @param connectionString - Database connection string
-* @param name - Name of the test database
-* @returns Test database instance and cleanup function
-*/
-async function defineTestDatabase(opts) {
-	const dbName = `test_w${process.env.VITEST_POOL_ID || "0"}_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
-	await ensureTemplateDatabase(opts.connectionString, opts.name, opts.logger);
-	const templateDbName = `${opts.name}_test_template`;
-	const maintenanceUrl = getMaintenanceDbUrl(opts.connectionString);
-	const maintenanceClient = new Client({ connectionString: maintenanceUrl });
-	await maintenanceClient.connect();
-	try {
-		await maintenanceClient.query(`CREATE DATABASE ${dbName} WITH TEMPLATE ${templateDbName}`);
-	} finally {
-		await maintenanceClient.end();
-	}
-	const testComponents = parsePostgresUrl(opts.connectionString);
-	testComponents.database = dbName;
-	const testPool = new Pool$1({ connectionString: buildPostgresUrl(testComponents) });
-	const db = drizzle({
-		client: testPool,
-		logger: opts.logger ? new DatabaseLogger(opts.logger) : void 0,
-		relations: opts.relations,
-		schema: opts.schema
-	});
-	const cleanUp = async () => {
-		await testPool.end();
-		const cleanupClient = new Client({ connectionString: maintenanceUrl });
-		await cleanupClient.connect();
-		try {
-			await cleanupClient.query(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1`, [dbName]);
-			await cleanupClient.query(`DROP DATABASE IF EXISTS ${dbName}`);
-		} catch (error) {
-			console.error("Could not drop test database:", error);
-		} finally {
-			await cleanupClient.end();
-		}
-	};
-	return {
-		cleanUp,
-		db,
-		dbName
-	};
-}
-/**
-* Parse PostgreSQL connection URL into components.
-*
-* @param connectionString - PostgreSQL connection URL
-* @returns Parsed URL components
-*/
-function parsePostgresUrl(connectionString) {
-	const url = new URL(connectionString);
-	return {
-		database: url.pathname.slice(1) || "postgres",
-		host: url.hostname,
-		password: decodeURIComponent(url.password),
-		port: Number.parseInt(url.port || "5432", 10),
-		user: decodeURIComponent(url.username)
-	};
-}
-/**
-* Build PostgreSQL connection URL from components.
-*
-* @param components - URL components
-* @returns PostgreSQL connection URL
-*/
-function buildPostgresUrl(components) {
-	const { user, password, host, port, database } = components;
-	return `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}/${database}`;
-}
-/**
-* Get connection URL for maintenance database operations.
-*
-* @param connectionString - Original connection string
-* @returns Connection string to maintenance database
-*/
-function getMaintenanceDbUrl(connectionString) {
-	const components = parsePostgresUrl(connectionString);
-	components.database = "postgres";
-	return buildPostgresUrl(components);
-}
-/**
-* Generate deterministic advisory lock ID from template database name.
-*
-* @param templateDbName - Template database name
-* @returns 32-bit integer lock ID
-*/
-function getAdvisoryLockId(templateDbName) {
-	let hash = 0;
-	for (let i = 0; i < templateDbName.length; i++) {
-		const char = templateDbName.charCodeAt(i);
-		hash = (hash << 5) - hash + char;
-		hash = hash & hash;
-	}
-	return Math.abs(hash);
-}
-/**
-* Ensure template database exists with migrations applied.
-*
-* Uses PostgreSQL advisory locks to prevent race conditions when multiple
-* test workers try to create the same template database concurrently.
-*
-* @param connectionString - Database connection string
-* @param name - Database name (e.g., "platform")
-* @param rootFolder - Root folder for migrations
-* @param logger - Optional logger
-*/
-async function ensureTemplateDatabase(connectionString, name, logger) {
-	const templateDbName = `${name}_test_template`;
-	const maintenanceClient = new Client({ connectionString: getMaintenanceDbUrl(connectionString) });
-	await maintenanceClient.connect();
-	const lockId = getAdvisoryLockId(templateDbName);
-	try {
-		await maintenanceClient.query("SELECT pg_advisory_lock($1)", [lockId]);
-		if ((await maintenanceClient.query("SELECT 1 FROM pg_database WHERE datname = $1", [templateDbName])).rowCount === 0) {
-			await maintenanceClient.query(`CREATE DATABASE ${templateDbName} WITH IS_TEMPLATE = true`);
-			const components = parsePostgresUrl(connectionString);
-			components.database = templateDbName;
-			const templatePool = new Pool$1({ connectionString: buildPostgresUrl(components) });
-			try {
-				await migrate(drizzle({
-					client: templatePool,
-					logger: logger ? new DatabaseLogger(logger) : void 0
-				}), defineMigrationOpts(name));
-			} finally {
-				await templatePool.end();
-			}
-		}
-	} finally {
-		await maintenanceClient.query("SELECT pg_advisory_unlock($1)", [lockId]);
-		await maintenanceClient.end();
-	}
-}
-
-//#endregion
-export { dbChanges, defineDatabase, defineMigrationOpts, defineTestDatabase, migrationsSchema };

package/dist/exports/api/event.d.mts

@@ -1,235 +0,0 @@
-import { Logger } from "./logger.mjs";
-import { Container } from "./container.mjs";
-import { z } from "zod";
-
-//#region src/api/event.d.ts
-
-/**
- * Context available to event handlers.
- */
-interface EventContext<TInput> {
-  /**
-   * The application container with access to db, mailer, logger, etc.
-   */
-  container: Container;
-  /**
-   * The validated input passed to this event.
-   */
-  input: TInput;
-}
-/**
- * Options for defining an event bus.
- */
-interface DefineEventBusOptions {
-  /**
-   * Redis URL for pub/sub.
-   */
-  dbUrl: string;
-  /**
-   * Logger instance for error reporting.
-   */
-  logger: Logger;
-}
-/**
- * The event bus type for container.
- */
-type EventBus = ReturnType<typeof defineEventBus>;
-/**
- * Defines the event bus for pub/sub messaging.
- * Uses Redis for cross-server communication.
- *
- * Algorithm:
- * 1. Create lazy Redis publisher client
- * 2. Create lazy Redis subscriber client
- * 3. Manage subscriptions via callback registry
- * 4. Provide publish/subscribe/close methods
- *
- * @param opts - Event bus configuration
- * @returns Event bus instance
- */
-declare function defineEventBus(opts: DefineEventBusOptions): {
-  /**
-   * Publish a message to a channel.
-   * Auto-connects on first call if not already connected.
-   *
-   * @param channel - Channel name
-   * @param message - Message payload (will be JSON stringified)
-   */
-  publish(channel: string, message: unknown): Promise<void>;
-  /**
-   * Subscribe to a channel. Returns unsubscribe function.
-   * Uses single connection with callback management.
-   *
-   * @param channel - Channel name
-   * @param callback - Callback for received messages
-   * @returns Unsubscribe function
-   */
-  subscribe(channel: string, callback: (message: unknown) => void): Promise<() => void>;
-  /**
-   * Check if a channel has any subscribers.
-   *
-   * @param channel - Channel name
-   * @returns true if channel has subscribers
-   */
-  hasSubscribers(channel: string): boolean;
-  /**
-   * Close the Redis connections.
-   */
-  close(): Promise<void>;
-};
-/**
- * Options for defining an event.
- */
-interface DefineEventOptions<TInput extends z.ZodType> {
-  /**
-   * Zod schema for validating event input.
-   */
-  input: TInput;
-  /**
-   * In-memory handler that runs only on the emitting server.
-   *
-   * @param ctx - Event context with container and input
-   */
-  run: (ctx: EventContext<z.infer<TInput>>) => Promise<void>;
-}
-/**
- * Event object returned by defineEvent.
- */
-interface Event<TInput> {
-  /**
-   * The event name (set during registration from filename).
-   */
-  readonly name: string | null;
-  /**
-   * Emit this event with the given input.
-   * Runs in-memory handler, then publishes to Redis (fire-and-forget).
-   *
-   * @param input - Input matching the event's input schema.
-   */
-  emit(input: TInput): Promise<void>;
-  /**
-   * The Zod schema for validating input.
-   */
-  inputSchema: z.ZodType<TInput>;
-  /**
-   * Register this event with the container. Called by the event loader.
-   *
-   * @param container - The application container
-   * @param name - The event name (derived from filename)
-   */
-  register(container: Container, name: string): void;
-  /**
-   * Subscribe to this event via Redis pub/sub.
-   * Use for tRPC subscriptions, SSE, WebSockets.
-   *
-   * @param handler - Handler called when event is emitted on any server
-   * @returns Unsubscribe function to cleanup the subscription
-   */
-  subscribe(handler: (ctx: EventContext<TInput>) => Promise<void>): Promise<() => void>;
-}
-/**
- * Defines a type-safe event with in-memory and Redis pub/sub support.
- *
- * Algorithm:
- * 1. Define event with input schema and in-memory run handler
- * 2. On emit(): validate input, run in-memory handler, publish to Redis (fire-and-forget)
- * 3. .subscribe() creates Redis subscription for tRPC/SSE/WebSocket handlers
- *
- * @example
- * ```typescript
- * // api/events/order-status.ts
- * export default defineEvent({
- *   input: z.object({
- *     orderId: z.string(),
- *     status: z.enum(["pending", "shipped", "delivered"]),
- *   }),
- *   async run(ctx) {
- *     ctx.container.logger.info(`Order ${ctx.input.orderId} is ${ctx.input.status}`);
- *   },
- * });
- *
- * // Emit from anywhere
- * await orderStatus.emit({ orderId: "123", status: "shipped" });
- *
- * // Subscribe (e.g., in tRPC router)
- * const unsubscribe = await orderStatus.subscribe(async (ctx) => {
- *   // Push to client via SSE/WebSocket
- * });
- * // Cleanup when client disconnects
- * unsubscribe();
- * ```
- */
-declare function defineEvent<TInput extends z.ZodType>(options: DefineEventOptions<TInput>): Event<z.infer<TInput>>;
-/**
- * Input schema for dbChangesEvent.
- */
-declare const dbChangeInputSchema: z.ZodObject<{
-  action: z.ZodEnum<{
-    DELETE: "DELETE";
-    INSERT: "INSERT";
-    UPDATE: "UPDATE";
-  }>;
-  newData: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-  oldData: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-  organizationId: z.ZodNullable<z.ZodString>;
-  tableName: z.ZodString;
-  timestamp: z.ZodString;
-  userId: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>;
-/**
- * Type for dbChangesEvent input.
- */
-type DbChangeInput = z.infer<typeof dbChangeInputSchema>;
-/**
- * Built-in event for database changes.
- * Emitted by trackDbChanges workflow.
- *
- * @example
- * ```typescript
- * // Subscribe to DB changes (e.g., in tRPC subscription)
- * import { dbChangesEvent } from "appos/api";
- *
- * const unsubscribe = await dbChangesEvent.subscribe(async (ctx) => {
- *   wsServer.publish("db-changes", JSON.stringify(ctx.input));
- * });
- *
- * // Cleanup when done
- * unsubscribe();
- * ```
- */
-declare const dbChangesEvent: Event<{
-  action: "DELETE" | "INSERT" | "UPDATE";
-  newData: Record<string, unknown> | null;
-  oldData: Record<string, unknown> | null;
-  organizationId: string | null;
-  tableName: string;
-  timestamp: string;
-  userId: string | null;
-}>;
-/**
- * Options for loading events.
- */
-interface LoadEventsOptions {
-  /**
-   * The application container.
-   */
-  container: Container;
-  /**
-   * Optional custom events directory path.
-   */
-  eventsDir?: string;
-}
-/**
- * Auto-discovers and registers all events from the given directory.
- *
- * Algorithm:
- * 1. Register built-in dbChangesEvent
- * 2. Glob all .ts files in the directory (excluding test files)
- * 3. Import each module's default export
- * 4. If it's an Event (has emit + subscribe), call register(container, name)
- *
- * @param opts - Load events options
- */
-declare function loadEvents(opts: LoadEventsOptions): Promise<void>;
-//#endregion
-export { DbChangeInput, DefineEventBusOptions, Event, EventBus, EventContext, dbChangeInputSchema, dbChangesEvent, defineEvent, defineEventBus, loadEvents };

package/dist/exports/api/event.mjs

@@ -1,236 +0,0 @@
-import { defineRedisClient } from "./redis.mjs";
-import { APPOS_DIR, EVENTS_DIR, FILE_EXT } from "./constants.mjs";
-import { z } from "zod";
-import { basename, join } from "node:path";
-import { glob } from "node:fs/promises";
-import { camelCase } from "es-toolkit";
-
-//#region src/api/event.ts
-/**
-* Defines the event bus for pub/sub messaging.
-* Uses Redis for cross-server communication.
-*
-* Algorithm:
-* 1. Create lazy Redis publisher client
-* 2. Create lazy Redis subscriber client
-* 3. Manage subscriptions via callback registry
-* 4. Provide publish/subscribe/close methods
-*
-* @param opts - Event bus configuration
-* @returns Event bus instance
-*/
-function defineEventBus(opts) {
-	const publisherClient = defineRedisClient({
-		logger: opts.logger,
-		url: opts.dbUrl
-	});
-	let subscriberClient = null;
-	const subscribers = /* @__PURE__ */ new Map();
-	return {
-		async publish(channel, message) {
-			await publisherClient.publish(channel, JSON.stringify(message));
-		},
-		async subscribe(channel, callback) {
-			if (!subscriberClient) {
-				subscriberClient = publisherClient.duplicate();
-				await subscriberClient.connect();
-			}
-			if (!subscribers.has(channel)) {
-				subscribers.set(channel, /* @__PURE__ */ new Set());
-				await subscriberClient.subscribe(channel, (msg) => {
-					const callbacks = subscribers.get(channel);
-					if (callbacks) {
-						let parsed;
-						try {
-							parsed = JSON.parse(msg);
-						} catch (err) {
-							opts.logger.error({
-								err,
-								channel,
-								msg
-							}, "Failed to parse event message");
-							return;
-						}
-						for (const cb of callbacks) try {
-							cb(parsed);
-						} catch (err) {
-							opts.logger.error({
-								err,
-								channel
-							}, "Event handler error");
-						}
-					}
-				});
-			}
-			subscribers.get(channel).add(callback);
-			return () => {
-				const callbacks = subscribers.get(channel);
-				if (callbacks) callbacks.delete(callback);
-			};
-		},
-		hasSubscribers(channel) {
-			const callbacks = subscribers.get(channel);
-			return callbacks !== void 0 && callbacks.size > 0;
-		},
-		async close() {
-			if (subscriberClient?.isOpen) await subscriberClient.quit();
-			if (publisherClient.isOpen) await publisherClient.quit();
-		}
-	};
-}
-/**
-* Defines a type-safe event with in-memory and Redis pub/sub support.
-*
-* Algorithm:
-* 1. Define event with input schema and in-memory run handler
-* 2. On emit(): validate input, run in-memory handler, publish to Redis (fire-and-forget)
-* 3. .subscribe() creates Redis subscription for tRPC/SSE/WebSocket handlers
-*
-* @example
-* ```typescript
-* // api/events/order-status.ts
-* export default defineEvent({
-*   input: z.object({
-*     orderId: z.string(),
-*     status: z.enum(["pending", "shipped", "delivered"]),
-*   }),
-*   async run(ctx) {
-*     ctx.container.logger.info(`Order ${ctx.input.orderId} is ${ctx.input.status}`);
-*   },
-* });
-*
-* // Emit from anywhere
-* await orderStatus.emit({ orderId: "123", status: "shipped" });
-*
-* // Subscribe (e.g., in tRPC router)
-* const unsubscribe = await orderStatus.subscribe(async (ctx) => {
-*   // Push to client via SSE/WebSocket
-* });
-* // Cleanup when client disconnects
-* unsubscribe();
-* ```
-*/
-function defineEvent(options) {
-	let container = null;
-	let eventName = null;
-	return {
-		inputSchema: options.input,
-		get name() {
-			return eventName;
-		},
-		register(c, name) {
-			container = c;
-			eventName = name;
-		},
-		async emit(input) {
-			if (!container || !eventName) throw new Error("Event not registered. Ensure the worker is started before emitting events.");
-			const validated = options.input.parse(input);
-			const ctx = {
-				container,
-				input: validated
-			};
-			await options.run(ctx);
-			container.eventBus.publish(eventName, validated).catch((err) => {
-				container.logger.error({
-					err,
-					event: eventName
-				}, "Redis publish failed");
-			});
-		},
-		async subscribe(handler) {
-			if (!container || !eventName) throw new Error("Event not registered. Ensure the worker is started before subscribing.");
-			return container.eventBus.subscribe(eventName, async (message) => {
-				const validated = options.input.parse(message);
-				const ctx = {
-					container,
-					input: validated
-				};
-				try {
-					await handler(ctx);
-				} catch (err) {
-					container.logger.error({
-						err,
-						event: eventName
-					}, "Event subscription handler error");
-				}
-			});
-		}
-	};
-}
-/**
-* Input schema for dbChangesEvent.
-*/
-const dbChangeInputSchema = z.object({
-	action: z.enum([
-		"INSERT",
-		"UPDATE",
-		"DELETE"
-	]),
-	newData: z.record(z.string(), z.unknown()).nullable(),
-	oldData: z.record(z.string(), z.unknown()).nullable(),
-	organizationId: z.string().nullable(),
-	tableName: z.string(),
-	timestamp: z.string(),
-	userId: z.string().nullable()
-});
-/**
-* Built-in event for database changes.
-* Emitted by trackDbChanges workflow.
-*
-* @example
-* ```typescript
-* // Subscribe to DB changes (e.g., in tRPC subscription)
-* import { dbChangesEvent } from "appos/api";
-*
-* const unsubscribe = await dbChangesEvent.subscribe(async (ctx) => {
-*   wsServer.publish("db-changes", JSON.stringify(ctx.input));
-* });
-*
-* // Cleanup when done
-* unsubscribe();
-* ```
-*/
-const dbChangesEvent = defineEvent({
-	input: dbChangeInputSchema,
-	async run() {}
-});
-/**
-* Extracts event name from filepath as camelCase.
-*/
-function getEventName(filepath) {
-	return camelCase(basename(filepath, ".ts"));
-}
-/**
-* Auto-discovers and registers all events from the given directory.
-*
-* Algorithm:
-* 1. Register built-in dbChangesEvent
-* 2. Glob all .ts files in the directory (excluding test files)
-* 3. Import each module's default export
-* 4. If it's an Event (has emit + subscribe), call register(container, name)
-*
-* @param opts - Load events options
-*/
-async function loadEvents(opts) {
-	const { container } = opts;
-	const eventsDir = opts.eventsDir ?? join(process.cwd(), APPOS_DIR, EVENTS_DIR);
-	dbChangesEvent.register(container, "dbChanges");
-	const files = await Array.fromAsync(glob(`${eventsDir}/**/*.${FILE_EXT}`, { exclude: [
-		"**/*.test.ts",
-		"**/*.spec.ts",
-		"**/*.test.js",
-		"**/*.spec.js"
-	] }));
-	for (const file of files) {
-		const mod = await import(file);
-		if (mod.default && typeof mod.default === "object") {
-			if ("emit" in mod.default && "subscribe" in mod.default) {
-				const name = getEventName(file);
-				mod.default.register(container, name);
-			}
-		}
-	}
-}
-
-//#endregion
-export { dbChangeInputSchema, dbChangesEvent, defineEvent, defineEventBus, loadEvents };