appos 0.3.5-0 → 0.3.7-0

package/dist/exports/api/config.mjs

@@ -1,72 +0,0 @@
-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,92 +0,0 @@
-//#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.d.mts

@@ -1,210 +0,0 @@
-import { Logger } from "./logger.mjs";
-import { Database } from "./database.mjs";
-import { Auth } from "./auth.mjs";
-import { Cache } from "./cache.mjs";
-import { Config } from "./config.mjs";
-import { EventBus } from "./event.mjs";
-import { Mailer } from "./mailer.mjs";
-import { Storage } from "./storage.mjs";
-import { i18n } from "i18next";
-import { CorsOptions } from "cors";
-import { Options } from "express-rate-limit";
-import { HelmetOptions } from "helmet";
-
-//#region src/api/container.d.ts
-
-/**
- * Server configuration for the HTTP server.
- */
-interface ServerConfig {
-  /**
-   * The host address the server will bind to.
-   *
-   * @default "0.0.0.0"
-   */
-  host?: string;
-  /**
-   * The port number the server will listen on.
-   */
-  port: number;
-  /**
-   * Request timeout in milliseconds. Requests exceeding this duration
-   * will receive a 408 Request Timeout response.
-   *
-   * @default 30000
-   */
-  timeout?: number;
-  /**
-   * Maximum request body size for JSON and URL-encoded payloads.
-   * Supports bytes.js format strings (e.g., "1mb", "500kb", "10mb").
-   *
-   * @default "1mb"
-   */
-  bodyLimit?: string;
-  /**
-   * The path for the health check endpoint.
-   *
-   * @default "/health"
-   */
-  healthPath?: string;
-  /**
-   * CORS configuration. Omit or set to undefined to disable.
-   *
-   * @example
-   * cors: { origin: "https://example.com", credentials: true }
-   */
-  cors?: CorsOptions;
-  /**
-   * Security headers configuration (via helmet). Omit or set to undefined to disable.
-   * Recommended for production deployments.
-   *
-   * @example
-   * helmet: { contentSecurityPolicy: false }  // Enable with CSP disabled
-   * helmet: {}  // Enable with all defaults
-   */
-  helmet?: HelmetOptions;
-  /**
-   * Rate limiting configuration. Array of express-rate-limit options.
-   * Each config is applied as a separate middleware - use `skip` function for path-specific limits.
-   * Redis store is automatically configured if `redisUrl` is provided.
-   *
-   * @example
-   * // Global rate limit
-   * rateLimit: [{ windowMs: 60000, limit: 100 }]
-   *
-   * @example
-   * // Path-specific rate limits
-   * rateLimit: [
-   *   { windowMs: 900000, limit: 5, skip: (req) => !req.path.startsWith("/api/auth") },
-   *   { windowMs: 60000, limit: 100 },  // Default for all other routes
-   * ]
-   */
-  rateLimit?: Options[];
-  /**
-   * Redis URL for rate limiting store (for multi-instance deployments).
-   * Server auto-connects and cleans up on shutdown.
-   * If omitted, uses in-memory store (not suitable for production clusters).
-   *
-   * @example
-   * redisUrl: "redis://localhost:6379"
-   */
-  redisUrl?: string;
-}
-/**
- * Worker configuration for the DBOS workflow worker.
- */
-interface WorkerConfig {
-  /**
-   * The system database URL for DBOS.
-   */
-  dbUrl: string;
-}
-/**
- * The base application container type that holds required services like
- * config, databases, and caches.
- */
-interface AppContainer<TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>> {
-  /**
-   * The application auth configuration.
-   */
-  auth: Auth<TDb>;
-  /**
-   * A map of caches available in the application.
-   */
-  cache: Record<string, Cache>;
-  /**
-   * The application configuration.
-   */
-  config: Config;
-  /**
-   * A map of databases available in the application.
-   */
-  db: TDb;
-  /**
-   * The i18n instance for internationalization.
-   */
-  i18n: i18n;
-  /**
-   * The logger instance for logging messages.
-   */
-  logger: Logger;
-  /**
-   * The event bus for in-memory and Redis pub/sub messaging.
-   */
-  eventBus: EventBus;
-  /**
-   * The mailer instance for sending emails.
-   */
-  mailer: Mailer;
-  /**
-   * Server configuration for the HTTP server.
-   */
-  server: ServerConfig;
-  /**
-   * A map of storage services available in the application.
-   */
-  storage: Record<"primary", Storage> & Record<string, Storage>;
-  /**
-   * Worker configuration for the DBOS workflow worker.
-   */
-  worker: WorkerConfig;
-}
-/**
- * Global namespace for user container augmentation.
- * Users can extend Container interface in their container.ts file.
- */
-declare global {
-  namespace AppOS {
-    interface Container {}
-  }
-}
-/**
- * The container type used throughout the application.
- * Merges base AppContainer with user's custom Container augmentations.
- */
-type Container = AppContainer & AppOS.Container;
-/**
- * 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,
- *     },
- *   });
- * }
- * ```
- */
-declare function defineAppContainer<T extends AppContainer>(container: T): T;
-//#endregion
-export { AppContainer, Container, ServerConfig, WorkerConfig, defineAppContainer };

package/dist/exports/api/container.mjs

@@ -1,49 +0,0 @@
-//#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.d.mts

@@ -1,101 +0,0 @@
-import { Logger } from "./logger.mjs";
-import * as drizzle_orm22 from "drizzle-orm";
-import { AnyRelations, EmptyRelations } from "drizzle-orm";
-import { PgTable } from "drizzle-orm/pg-core";
-import * as drizzle_orm_node_postgres0 from "drizzle-orm/node-postgres";
-import * as pg0 from "pg";
-import pg from "pg";
-import { MigrationConfig } from "drizzle-orm/migrator";
-
-//#region src/api/database.d.ts
-type PoolConfig = pg.PoolConfig;
-/**
- * Extract qualified table names from db object.
- */
-type QualifiedTableNames<TDb> = { [K in keyof TDb]: TDb[K] extends {
-  _: {
-    fullSchema: infer S;
-  };
-} ? `${K & string}.${keyof S & string}` : never }[keyof TDb];
-/**
- * The schema used for migrations.
- */
-declare const migrationsSchema = "public";
-/**
- * The type of migration (schema or data).
- */
-type MigrationType = "schema" | "data";
-/**
- * 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
- */
-declare function defineMigrationOpts(name: string, type?: MigrationType): MigrationConfig;
-/**
- * Options for defining the database.
- */
-interface DefineDatabaseOptions<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations> {
-  logger: Logger;
-  poolConfig: PoolConfig;
-  relations?: TRelations;
-  schema?: TSchema;
-}
-/**
- * The database type.
- */
-type Database = Awaited<ReturnType<typeof defineDatabase>>;
-/**
- * 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.
- */
-declare function dbChanges<T extends PgTable>(table: T): {
-  _table: drizzle_orm22.SQL.Aliased<string>;
-  old: drizzle_orm22.SQL.Aliased<({ [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true ? T["_"]["columns"][Key]["_"]["data"] : T["_"]["columns"][Key]["_"]["data"] | null } extends infer T_1 ? { [K in keyof T_1]: T_1[K] } : never) | null>;
-  new: drizzle_orm22.SQL.Aliased<({ [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true ? T["_"]["columns"][Key]["_"]["data"] : T["_"]["columns"][Key]["_"]["data"] | null } extends infer T_2 ? { [K in keyof T_2]: T_2[K] } : never) | null>;
-};
-/**
- * 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.
- */
-declare function defineDatabase<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations>(opts: DefineDatabaseOptions<TSchema, TRelations>): Promise<drizzle_orm_node_postgres0.NodePgDatabase<TSchema, TRelations> & {
-  $client: pg0.Pool;
-}>;
-/**
- * Options for defining a test database.
- */
-interface DefineTestDatabaseOptions<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations> {
-  connectionString: string;
-  logger: Logger;
-  name: string;
-  schema: TSchema;
-  relations: TRelations;
-}
-/**
- * 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
- */
-declare function defineTestDatabase<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations>(opts: DefineTestDatabaseOptions<TSchema, TRelations>): Promise<{
-  cleanUp: () => Promise<void>;
-  db: drizzle_orm_node_postgres0.NodePgDatabase<TSchema, TRelations> & {
-    $client: pg0.Pool;
-  };
-  dbName: string;
-}>;
-//#endregion
-export { Database, DefineDatabaseOptions, DefineTestDatabaseOptions, MigrationType, QualifiedTableNames, dbChanges, defineDatabase, defineMigrationOpts, defineTestDatabase, migrationsSchema };