appos 0.3.2-0 → 0.3.4-0

package/dist/exports/api/cache.mjs

@@ -1 +1,28 @@
-import{defineRedisClient as e}from"./redis.mjs";import{createKeyv as t}from"@keyv/redis";function n({url:n,logger:r,options:i}){let a=t(e({logger:r,url:n}),i);return a.on(`error`,e=>{r.error({err:e},`Cache Keyv error`)}),a}export{n as defineCache};
+import { defineRedisClient } from "./redis.mjs";
+import { createKeyv } from "@keyv/redis";
+
+//#region src/api/cache.ts
+/**
+* Define the cache instance using shared Redis client.
+* Connection is lazy - only connects when first cache operation is performed.
+*
+* Algorithm:
+* 1. Create Redis client using defineRedisClient() (lazy connection)
+* 2. Pass client to createKeyv() - connection happens on first use
+*
+* @param opts - The options for defining the cache.
+* @returns The cache instance.
+*/
+function defineCache({ url, logger, options }) {
+	const cache = createKeyv(defineRedisClient({
+		logger,
+		url
+	}), options);
+	cache.on("error", (err) => {
+		logger.error({ err }, "Cache Keyv error");
+	});
+	return cache;
+}
+
+//#endregion
+export { defineCache };

package/dist/exports/api/config.mjs

@@ -1 +1,72 @@
-import{z as e}from"zod";const t=e.object({APP_NAME:e.string().default(`AppOS`),APP_DESC:e.string().default(`The app operating system to build your business.`),APP_VERSION:e.string().default(`development`)});function n(e){let t={...e},n=new Set;function r(e,i){if(n.has(e))throw Error(`Circular reference detected in environment variable: ${e}`);n.add(e);let a=i.replace(/\{\{([^}]+)\}\}/g,(e,n)=>{let i=n.trim();if(!i)return e;let a=t[i];return a===void 0?e:a.includes(`{{`)?r(i,a):a});return n.delete(e),a}for(let[e,n]of Object.entries(t))n?.includes(`{{`)&&(t[e]=r(e,n));return t}function r(e){let r=t.extend(e.shape),i={};for(let[e,t]of Object.entries(r.shape)){let n=t;for(;n;){let t=n.def;if(t.defaultValue!==void 0){let n=typeof t.defaultValue==`function`?t.defaultValue():t.defaultValue;typeof n==`string`&&(i[e]=n);break}n=t.innerType||t.schema}}let a={...i};for(let[e,t]of Object.entries(process.env))t!==void 0&&(a[e]=t);return r.parse(n(a))}export{t as baseSchema,r as defineConfig};
+import { z } from "zod";
+
+//#region src/api/config.ts
+/**
+* The config base schema.
+*/
+const baseSchema = z.object({
+	APP_NAME: z.string().default("AppOS"),
+	APP_DESC: z.string().default("The app operating system to build your business."),
+	APP_VERSION: z.string().default("development")
+});
+/**
+* Expands variables in environment values using {{VAR_NAME}} syntax.
+* Supports nested expansion and handles circular references.
+*
+* If a variable is not found, the placeholder is preserved in the output.
+* Variables can reference other variables recursively.
+*
+* @param env Environment variables object
+* @returns Environment variables with expanded values
+*/
+function expandVariables(env) {
+	const expanded = { ...env };
+	const expanding = /* @__PURE__ */ new Set();
+	function expand(key, value) {
+		if (expanding.has(key)) throw new Error(`Circular reference detected in environment variable: ${key}`);
+		expanding.add(key);
+		const result = value.replace(/\{\{([^}]+)\}\}/g, (match, varName) => {
+			const trimmedVarName = varName.trim();
+			if (!trimmedVarName) return match;
+			const varValue = expanded[trimmedVarName];
+			if (varValue === void 0) return match;
+			if (varValue.includes("{{")) return expand(trimmedVarName, varValue);
+			return varValue;
+		});
+		expanding.delete(key);
+		return result;
+	}
+	for (const [key, value] of Object.entries(expanded)) if (value?.includes("{{")) expanded[key] = expand(key, value);
+	return expanded;
+}
+/**
+* Creates a configuration object by merging base config with user-defined schema.
+*
+* Variables in default values are expanded after defaults are applied.
+* For example: `DATABASE_URL: z.string().default("postgres://{{DB_HOST}}:5432")`
+*
+* @param userSchema User-defined Zod schema to merge with base config.
+* @returns Parsed and validated configuration object.
+*/
+function defineConfig(userSchema) {
+	const mergedSchema = baseSchema.extend(userSchema.shape);
+	const defaults = {};
+	for (const [key, fieldSchema] of Object.entries(mergedSchema.shape)) {
+		let current = fieldSchema;
+		while (current) {
+			const def = current.def;
+			if (def.defaultValue !== void 0) {
+				const defaultValue = typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+				if (typeof defaultValue === "string") defaults[key] = defaultValue;
+				break;
+			}
+			current = def.innerType || def.schema;
+		}
+	}
+	const merged = { ...defaults };
+	for (const [key, value] of Object.entries(process.env)) if (value !== void 0) merged[key] = value;
+	return mergedSchema.parse(expandVariables(merged));
+}
+
+//#endregion
+export { baseSchema, defineConfig };

package/dist/exports/api/constants.mjs

@@ -1 +1,92 @@
-const e=`api`,t=`databases`,n=`routes`,r=`workflows`,i=`events`,a=`public`,o=`locales`,s=process.env.NODE_ENV===`production`?`js`:`ts`;export{e as APPOS_DIR,t as DATABASES_DIR,i as EVENTS_DIR,s as FILE_EXT,o as LOCALES_DIR,a as PUBLIC_DIR,n as ROUTES_DIR,r as WORKFLOWS_DIR};
+//#region src/constants.ts
+/**
+* Directory constants used throughout the AppOS framework.
+*
+* These constants define the conventional directory structure for AppOS applications.
+* All paths are relative to the project root unless otherwise specified.
+*/
+/**
+* The main AppOS directory containing application code.
+*
+* Expected structure:
+* - `<project-root>/api/container.ts` - Application container definition
+* - `<project-root>/api/commands/` - CLI commands
+* - `<project-root>/api/databases/` - Database schemas and migrations
+* - `<project-root>/api/emails/` - Email templates
+* - `<project-root>/api/events/` - Event definitions
+* - `<project-root>/api/middleware/` - Custom middleware
+* - `<project-root>/api/routes/` - API routes
+* - `<project-root>/api/workflows/` - Background workflows
+*
+* @default "api"
+*/
+const APPOS_DIR = "api";
+/**
+* Directory for database schemas and migrations.
+*
+* Expected structure:
+* - `<APPOS_DIR>/databases/<db-name>/schema.ts` - Database schema
+* - `<APPOS_DIR>/databases/<db-name>/schema-migrations/` - Migration files
+*
+* @default "databases"
+*/
+const DATABASES_DIR = "databases";
+/**
+* Directory for API route handlers.
+*
+* Expected structure:
+* - `<APPOS_DIR>/routes/<route-name>.ts` - Route handler files
+*
+* @default "routes"
+*/
+const ROUTES_DIR = "routes";
+/**
+* Directory for background workflow definitions.
+*
+* Expected structure:
+* - `<APPOS_DIR>/workflows/<workflow-name>.ts` - Workflow files
+*
+* @default "workflows"
+*/
+const WORKFLOWS_DIR = "workflows";
+/**
+* Directory for event definitions and subscriptions.
+*
+* Expected structure:
+* - `<APPOS_DIR>/events/<event-name>.ts` - Event definition files
+* - `<APPOS_DIR>/events/<subscription-name>.ts` - Event subscription files
+*
+* @default "events"
+*/
+const EVENTS_DIR = "events";
+/**
+* Directory for public static assets.
+*
+* Expected structure:
+* - `<project-root>/public/` - Public directory root
+* - `<project-root>/public/locales/` - i18n translation files
+*
+* @default "public"
+*/
+const PUBLIC_DIR = process.env.NODE_ENV === "production" ? "client" : "public";
+/**
+* Directory for i18n locale/translation files (relative to PUBLIC_DIR).
+*
+* Expected structure:
+* - `<PUBLIC_DIR>/locales/<lng>/<ns>.json` - Translation files
+*
+* @default "locales"
+*/
+const LOCALES_DIR = "locales";
+/**
+* File extension for code files based on environment.
+*
+* In development: `.ts` (TypeScript source files)
+* In production: `.js` (bundled JavaScript files)
+*
+* @default "ts" in development, "js" in production
+*/
+const FILE_EXT = process.env.NODE_ENV === "production" ? "js" : "ts";
+
+//#endregion
+export { APPOS_DIR, DATABASES_DIR, EVENTS_DIR, FILE_EXT, LOCALES_DIR, PUBLIC_DIR, ROUTES_DIR, WORKFLOWS_DIR };

package/dist/exports/api/container.mjs

@@ -1 +1,49 @@
-function e(e){return e}export{e as defineAppContainer};
+//#region src/api/container.ts
+/**
+* Defines an application container with type-safe validation and inference.
+*
+* This helper function ensures that:
+* 1. All required base fields (config, cache, db) are provided
+* 2. Custom fields are fully preserved in the inferred type
+* 3. TypeScript provides autocomplete for all fields in commands/routes
+*
+* @template T - The container type extending AppContainer
+* @param container - The container object with required and custom fields
+* @returns The same container object with full type inference
+*
+* @example
+* ```typescript
+* // In your api/main.ts file:
+* export async function defineContainer() {
+*   const config = defineConfig(z.object({
+*     PORT: z.coerce.number().default(3000),
+*     EVENTS_DB_URL: z.string(),
+*     WORKER_DB_URL: z.string(),
+*   }));
+*   const logger = defineLogger({ level: config.LOG_LEVEL });
+*
+*   return defineAppContainer({
+*     auth: defineAuth({ config }),
+*     cache: {},
+*     config,
+*     db: {},
+*     eventBus: defineEventBus({ dbUrl: config.EVENTS_DB_URL, logger }),
+*     i18n: await defineI18n({ ... }),
+*     logger,
+*     mailer: defineMailer({ ... }),
+*     server: {
+*       port: config.PORT,
+*     },
+*     worker: {
+*       dbUrl: config.WORKER_DB_URL,
+*     },
+*   });
+* }
+* ```
+*/
+function defineAppContainer(container) {
+	return container;
+}
+
+//#endregion
+export { defineAppContainer };

package/dist/exports/api/database.mjs

@@ -1 +1,218 @@
-import{APPOS_DIR as e,DATABASES_DIR as t}from"./constants.mjs";import{getTableName as n,sql as r}from"drizzle-orm";import{join as i}from"node:path";import{drizzle as a}from"drizzle-orm/node-postgres";import{migrate as o}from"drizzle-orm/node-postgres/migrator";import{Client as s,Pool as c}from"pg";const l=`public`;function u(n,r=`schema`){let a=r===`schema`?`schema-migrations`:`data-migrations`,o=r===`schema`?`schema-migrations`:`data-migrations`;return{migrationsFolder:`${i(e,t)}/${n}/${a}`,migrationsSchema:l,migrationsTable:o}}var d=class{#e;constructor(e){this.#e=e}logQuery(e,t){this.#e.info(t,e)}};function f(e){let t=n(e);return{_table:r`${r.raw(`'${t}'`)}`.as(`_table`),old:r`to_jsonb(OLD.*)`.as(`old`),new:r`to_jsonb(NEW.*)`.as(`new`)}}async function p(e){return a({client:new c({application_name:`appos`,max:16,...e.poolConfig}),logger:new d(e.logger),relations:e.relations,schema:e.schema})}async function m(e){let t=`test_w${process.env.VITEST_POOL_ID||`0`}_${Date.now()}_${Math.random().toString(36).substring(2,8)}`;await y(e.connectionString,e.name,e.logger);let n=`${e.name}_test_template`,r=_(e.connectionString),i=new s({connectionString:r});await i.connect();try{await i.query(`CREATE DATABASE ${t} WITH TEMPLATE ${n}`)}finally{await i.end()}let o=h(e.connectionString);o.database=t;let l=new c({connectionString:g(o)});return{cleanUp:async()=>{await l.end();let e=new s({connectionString:r});await e.connect();try{await e.query(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1`,[t]),await e.query(`DROP DATABASE IF EXISTS ${t}`)}catch(e){console.error(`Could not drop test database:`,e)}finally{await e.end()}},db:a({client:l,logger:e.logger?new d(e.logger):void 0,relations:e.relations,schema:e.schema}),dbName:t}}function h(e){let t=new URL(e);return{database:t.pathname.slice(1)||`postgres`,host:t.hostname,password:decodeURIComponent(t.password),port:Number.parseInt(t.port||`5432`,10),user:decodeURIComponent(t.username)}}function g(e){let{user:t,password:n,host:r,port:i,database:a}=e;return`postgresql://${encodeURIComponent(t)}:${encodeURIComponent(n)}@${r}:${i}/${a}`}function _(e){let t=h(e);return t.database=`postgres`,g(t)}function v(e){let t=0;for(let n=0;n<e.length;n++){let r=e.charCodeAt(n);t=(t<<5)-t+r,t&=t}return Math.abs(t)}async function y(e,t,n){let r=`${t}_test_template`,i=new s({connectionString:_(e)});await i.connect();let l=v(r);try{if(await i.query(`SELECT pg_advisory_lock($1)`,[l]),(await i.query(`SELECT 1 FROM pg_database WHERE datname = $1`,[r])).rowCount===0){await i.query(`CREATE DATABASE ${r} WITH IS_TEMPLATE = true`);let s=h(e);s.database=r;let l=new c({connectionString:g(s)});try{await o(a({client:l,logger:n?new d(n):void 0}),u(t))}finally{await l.end()}}}finally{await i.query(`SELECT pg_advisory_unlock($1)`,[l]),await i.end()}}export{f as dbChanges,p as defineDatabase,u as defineMigrationOpts,m as defineTestDatabase,l as migrationsSchema};
+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 { Client, Pool } from "pg";
+
+//#region src/api/database.ts
+/**
+* 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({
+			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({ 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({ 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 };