appos 0.2.1 → 0.2.3-0

package/dist/exports/cli/context.d.mts

@@ -0,0 +1,170 @@
+import { Container } from "./api/container.mjs";
+import * as p from "@clack/prompts";
+
+//#region src/cli/context.d.ts
+
+/**
+ * Command context providing beautiful output, prompts, and utilities.
+ * Uses @clack/prompts for consistent, professional CLI formatting.
+ *
+ * @template C - Container type (defaults to base Container)
+ * @template A - Arguments type inferred from command's Zod args schema
+ * @template O - Options type inferred from command's Zod opts schema
+ */
+interface CommandContext<C extends Container = Container, A = readonly unknown[], O = Record<string, unknown>> {
+  /**
+   * The parsed command-line arguments.
+   * Type is inferred from the command's Zod args schema.
+   */
+  readonly args: A;
+  /**
+   * Prompts the user for single-line text input.
+   * @see https://www.clack.cc for prompt options
+   */
+  ask: typeof p.text;
+  /**
+   * Displays a cancellation message and exits the process with code 0.
+   * @param message - Optional cancellation message (defaults to "Cancelled")
+   */
+  cancel(message?: string): never;
+  /**
+   * Prompts the user for dropdown selection from a list of options.
+   * @see https://www.clack.cc for prompt options
+   */
+  choice: typeof p.select;
+  /**
+   * Releases all container resources including database connections and cache clients.
+   * Must be called before the command exits to prevent resource leaks.
+   */
+  cleanup(): Promise<void>;
+  /**
+   * Displays a dimmed comment line for secondary information.
+   * @param message - The comment text to display
+   */
+  comment(message: string): void;
+  /**
+   * Prompts the user for yes/no confirmation.
+   * @see https://www.clack.cc for prompt options
+   */
+  confirm: typeof p.confirm;
+  /**
+   * The dependency injection container providing access to services.
+   * Includes database connections, cache clients, logger, mailer, and configuration.
+   */
+  readonly container: C;
+  /**
+   * Displays an error message with the error symbol.
+   * @param message - The error message to display
+   */
+  error(message: string): void;
+  /**
+   * Executes a shell command asynchronously.
+   * @param command - The command to execute
+   * @param args - Array of command arguments
+   * @throws Error if the command exits with a non-zero code
+   */
+  exec(command: string, args: string[]): Promise<void>;
+  /**
+   * Displays an error message and terminates the process with exit code 1.
+   * @param message - The error message to display before exiting
+   */
+  fail(message: string): never;
+  /**
+   * Groups multiple prompts together for sequential execution.
+   * @see https://www.clack.cc for group options
+   */
+  group: typeof p.group;
+  /**
+   * Displays an informational message with the info symbol.
+   * @param message - The info message to display
+   */
+  info(message: string): void;
+  /**
+   * Displays the command intro header.
+   * @param title - The command name or title to display
+   */
+  intro(title: string): void;
+  /**
+   * Checks if a prompt result indicates user cancellation (Ctrl+C).
+   * @param value - The prompt result to check
+   * @returns True if the user cancelled the prompt
+   */
+  isCancel: typeof p.isCancel;
+  /**
+   * Displays a plain text line.
+   * @param message - The text to display
+   */
+  line(message: string): void;
+  /**
+   * Prompts the user to select multiple options from a list.
+   * @see https://www.clack.cc for multiselect options
+   */
+  multiselect: typeof p.multiselect;
+  /**
+   * Displays a formatted note box with optional title.
+   * @param message - The note content
+   * @param title - Optional title for the note
+   */
+  note(message: string, title?: string): void;
+  /**
+   * The parsed command-line options.
+   * Type is inferred from the command's Zod opts schema.
+   */
+  readonly opts: O;
+  /**
+   * Displays the command outro footer.
+   * @param message - Optional completion message (defaults to "Done")
+   */
+  outro(message?: string): void;
+  /**
+   * Prompts the user for password input with hidden characters.
+   * @see https://www.clack.cc for prompt options
+   */
+  secret: typeof p.password;
+  /**
+   * Executes an async function while displaying an animated spinner.
+   * Use for long-running operations like starting containers.
+   * @template T - Return type of the task function
+   * @param message - Message to display while spinning
+   * @param fn - Async function to execute
+   * @returns The result of the task function
+   */
+  spinner<T>(message: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Displays a step message indicating progress.
+   * @param message - The step description
+   */
+  step(message: string): void;
+  /**
+   * Displays a success message with the success symbol.
+   * @param message - The success message to display
+   */
+  success(message: string): void;
+  /**
+   * Displays data in a formatted note box as a table.
+   * @param headers - Array of column header strings
+   * @param rows - 2D array of cell values
+   */
+  table(headers: string[], rows: string[][]): void;
+  /**
+   * Executes an async function and displays the result with timing.
+   * @template T - Return type of the task function
+   * @param name - Display name for the task
+   * @param fn - Async function to execute
+   * @returns The result of the task function
+   */
+  task<T>(name: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Displays a task status line without executing any function.
+   * @param name - Display name for the task
+   * @param status - Status text to display
+   */
+  taskStatus(name: string, status: string): void;
+  /**
+   * Displays a warning message with the warning symbol.
+   * @param message - The warning message to display
+   */
+  warn(message: string): void;
+}
+//#endregion
+export { CommandContext };

package/dist/exports/cli/index.d.mts

@@ -0,0 +1,3 @@
+import { CommandContext } from "./context.mjs";
+import { Command, defineCommand } from "./command.mjs";
+export { type Command, type CommandContext, defineCommand };

package/dist/exports/cli/index.mjs

@@ -0,0 +1 @@
+import{defineCommand as e}from"./command.mjs";export{e as defineCommand};

package/dist/exports/devtools/index.d.ts

@@ -0,0 +1,3 @@
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
+export { ReactQueryDevtools, TanStackRouterDevtools };

package/dist/exports/devtools/index.js

@@ -0,0 +1 @@
+import{ReactQueryDevtools as e}from"@tanstack/react-query-devtools";import{TanStackRouterDevtools as t}from"@tanstack/react-router-devtools";export{e as ReactQueryDevtools,t as TanStackRouterDevtools};

package/dist/exports/instrumentation.d.mts

@@ -0,0 +1 @@
+export * from "@opentelemetry/api";

package/dist/exports/instrumentation.mjs

@@ -0,0 +1 @@
+import{register as e}from"node:module";import{getNodeAutoInstrumentations as t}from"@opentelemetry/auto-instrumentations-node";import{OTLPTraceExporter as n}from"@opentelemetry/exporter-trace-otlp-http";import{PinoInstrumentation as r}from"@opentelemetry/instrumentation-pino";import{resourceFromAttributes as i}from"@opentelemetry/resources";import{NodeSDK as a}from"@opentelemetry/sdk-node";import{BatchSpanProcessor as o}from"@opentelemetry/sdk-trace-node";import{ATTR_SERVICE_NAME as s,ATTR_SERVICE_VERSION as c}from"@opentelemetry/semantic-conventions";export*from"@opentelemetry/api";e(`@opentelemetry/instrumentation/hook.mjs`,import.meta.url);const l={name:process.env.APP_NAME||`appos`,version:process.env.APP_VERSION||`development`};new a({resource:i({[s]:l.name,[c]:l.version}),spanProcessors:[new o(new n({url:process.env.OTEL_EXPORTER_OTLP_ENDPOINT||`http://localhost:4318/v1/traces`,headers:process.env.OTEL_EXPORTER_OTLP_HEADERS?JSON.parse(process.env.OTEL_EXPORTER_OTLP_HEADERS):void 0}))],instrumentations:[t({"@opentelemetry/instrumentation-fs":{enabled:!1},"@opentelemetry/instrumentation-dns":{enabled:!1}}),new r({logHook:(e,t)=>{t[`service.name`]=l.name}})]}).start();export{};

package/dist/exports/tests/_virtual/rolldown_runtime.mjs

@@ -0,0 +1 @@
+var e=Object.defineProperty,t=Object.getOwnPropertyDescriptor,n=Object.getOwnPropertyNames,r=Object.prototype.hasOwnProperty,i=(t,n)=>{let r={};for(var i in t)e(r,i,{get:t[i],enumerable:!0});return n&&e(r,Symbol.toStringTag,{value:`Module`}),r},a=(i,a,o,s)=>{if(a&&typeof a==`object`||typeof a==`function`)for(var c=n(a),l=0,u=c.length,d;l<u;l++)d=c[l],!r.call(i,d)&&d!==o&&e(i,d,{get:(e=>a[e]).bind(null,d),enumerable:!(s=t(a,d))||s.enumerable});return i},o=(e,t,n)=>(a(e,t,`default`),n&&a(n,t,`default`));export{i as __export,o as __reExport};

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

@@ -0,0 +1,86 @@
+import { DefineTestDatabaseOptions, defineTestDatabase } from "./packages/appos/src/api/database.mjs";
+import { AppContainer } from "./packages/appos/src/api/container.mjs";
+import { index_d_exports } from "./packages/appos/src/api/index.mjs";
+import supertestOriginal from "supertest";
+import { TestAPI } from "vitest";
+import { Express } from "ultimate-express";
+import * as supertest_lib_agent0 from "supertest/lib/agent";
+
+//#region src/tests/api.d.ts
+type AppOSApi = typeof index_d_exports;
+/**
+ * Type-safe options for overriding default API mocks.
+ * Each override must match the exact signature of the original function.
+ */
+interface DefineApiMocksOptions {
+  defineDatabase?: AppOSApi["defineDatabase"];
+  defineStorage?: AppOSApi["defineStorage"];
+  defineCache?: AppOSApi["defineCache"];
+  defineLogger?: AppOSApi["defineLogger"];
+  defineMailer?: AppOSApi["defineMailer"];
+  defineEventBus?: AppOSApi["defineEventBus"];
+  defineAuth?: AppOSApi["defineAuth"];
+  defineI18n?: AppOSApi["defineI18n"];
+}
+/**
+ * Factory for vi.mock("appos/api").
+ * Intercepts define* calls and replaces them with test versions.
+ *
+ * @param overrides - Optional type-safe overrides for specific define* functions
+ * @returns Mock factory function for vi.mock
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * vi.mock("appos/api", defineApiMocks());
+ *
+ * // With custom logger (must match original signature)
+ * vi.mock("appos/api", defineApiMocks({
+ *   defineLogger: async (opts) => customLogger,
+ * }));
+ * ```
+ */
+declare function defineApiMocks(overrides?: DefineApiMocksOptions): (importOriginal: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>;
+/**
+ * Creates a supertest instance for testing ultimate-express apps.
+ *
+ * @param app The ultimate-express application instance.
+ *
+ * @example
+ * ```typescript
+ * import { request } from "appos/tests/api";
+ * import express from "ultimate-express";
+ *
+ * const app = express();
+ * app.get("/", (req, res) => res.json({ ok: true }));
+ *
+ * const response = await request(app).get("/");
+ * expect(response.body).toEqual({ ok: true });
+ * ```
+ */
+declare function request(app: Express): supertest_lib_agent0<supertestOriginal.SuperTestStatic.Test>;
+/**
+ * Creates a serverTest fixture from a defineContainer function.
+ * Container type is inferred from defineContainer's return type.
+ *
+ * @param defineContainer - The app's container factory function
+ * @param containerOverrides - Optional type-safe overrides for container fields
+ * @returns Vitest test with app and container fixtures
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * export const serverTest = defineServerTest(defineContainer);
+ *
+ * // With container overrides (type-safe)
+ * export const serverTestCustom = defineServerTest(defineContainer, {
+ *   config: { APP_NAME: "custom-test" },
+ * });
+ * ```
+ */
+declare function defineServerTest<TContainer extends AppContainer>(defineContainer: () => Promise<TContainer>, containerOverrides?: Partial<TContainer>): TestAPI<{
+  app: Express;
+  container: TContainer;
+}>;
+//#endregion
+export { DefineApiMocksOptions, type DefineTestDatabaseOptions, defineApiMocks, defineServerTest, defineTestDatabase, request };

package/dist/exports/tests/api.mjs

@@ -0,0 +1 @@
+import{defineTestDatabase as e}from"./packages/appos/src/api/database.mjs";import{defineServer as t}from"./packages/appos/src/api/server.mjs";import{mock_exports as n}from"./mock.mjs";import{mkdirSync as r,mkdtempSync as i}from"node:fs";import{rm as a}from"node:fs/promises";import{tmpdir as o}from"node:os";import{join as s}from"node:path";import c from"supertest";import{test as l}from"vitest";let u=[],d=(0,n.mock)();function f(){u=[],d=(0,n.mock)()}function p(t){return async c=>{let l=await c(),f=async t=>{let n=new URL(t.poolConfig.connectionString||`postgres://postgres:postgres@localhost:5432/test`),r=await e({connectionString:n.toString(),logger:d,name:n.pathname.slice(1)||`test`,schema:t.schema??{},relations:t.relations??{}});return u.push(r.cleanUp),r.db},p=e=>{let t=i(s(o(),`test-storage-`)),n={};for(let i of Object.keys(e.disks||{})){let e=s(t,i);r(e,{recursive:!0}),n[i]={location:e}}return u.push(()=>a(t,{recursive:!0,force:!0})),l.defineStorage({database:e.database,default:e.default,disks:n})};return{...l,defineDatabase:t?.defineDatabase??f,defineStorage:t?.defineStorage??p,defineCache:t?.defineCache??(()=>(0,n.mock)()),defineLogger:t?.defineLogger??(async()=>d),defineMailer:t?.defineMailer??(async()=>(0,n.mock)()),defineEventBus:t?.defineEventBus??(()=>(0,n.mockDeep)()),defineAuth:t?.defineAuth??(()=>(0,n.mockDeep)()),defineI18n:t?.defineI18n??(async()=>(0,n.mock)())}}}function m(e){let t=e.address?.bind(e);return e.address=()=>{let e=t?.();return e&&e.port===void 0?null:e},e.close||=t=>{e.uwsApp&&e.uwsApp.close(),t?.()},e}function h(e){return c(m(e))}function g(e,t){let n={...e};for(let r of Object.keys(t)){let i=t[r],a=e[r];i!==void 0&&typeof i==`object`&&i&&!Array.isArray(i)&&typeof a==`object`&&a&&!Array.isArray(a)?n[r]=g(a,i):i!==void 0&&(n[r]=i)}return n}function _(e,n){return l.extend({container:async({},t)=>{f();let r=await e();await t(n?g(r,n):r);for(let e of u.reverse())await e()},app:async({container:e},n)=>{await n((await t({container:e})).app)}})}export{p as defineApiMocks,_ as defineServerTest,e as defineTestDatabase,h as request};

package/dist/exports/tests/mock.d.mts

@@ -0,0 +1 @@
+export * from "vitest-mock-extended";

package/dist/exports/tests/mock.mjs

@@ -0,0 +1 @@
+import{__reExport as e}from"./_virtual/rolldown_runtime.mjs";export*from"vitest-mock-extended";var t={};import*as n from"vitest-mock-extended";e(t,n);export{t as mock_exports};

package/dist/exports/tests/node_modules/.bun/change-case@5.4.4/node_modules/change-case/dist/index.mjs

@@ -0,0 +1 @@
+const e=/([\p{Ll}\d])(\p{Lu})/gu,t=/(\p{Lu})([\p{Lu}][\p{Ll}])/gu,n=/(\d)\p{Ll}|(\p{L})\d/u,r=/[^\p{L}\d]+/giu,i=`$1\0$2`;function a(n){let a=n.trim();a=a.replace(e,i).replace(t,i),a=a.replace(r,`\0`);let o=0,s=a.length;for(;a.charAt(o)===`\0`;)o++;if(o===s)return[];for(;a.charAt(s-1)===`\0`;)s--;return a.slice(o,s).split(/\0/g)}function o(e){let t=a(e);for(let e=0;e<t.length;e++){let r=t[e],i=n.exec(r);if(i){let n=i.index+(i[1]??i[2]).length;t.splice(e,1,r.slice(0,n),r.slice(n))}}return t}function s(e,t){let[n,r,i]=f(e,t),a=c(t?.locale),o=l(t?.locale),s=t?.mergeAmbiguousCharacters?u(a,o):d(a,o);return n+r.map((e,t)=>t===0?a(e):s(e,t)).join(t?.delimiter??``)+i}function c(e){return e===!1?e=>e.toLowerCase():t=>t.toLocaleLowerCase(e)}function l(e){return e===!1?e=>e.toUpperCase():t=>t.toLocaleUpperCase(e)}function u(e,t){return n=>`${t(n[0])}${e(n.slice(1))}`}function d(e,t){return(n,r)=>{let i=n[0];return(r>0&&i>=`0`&&i<=`9`?`_`+i:t(i))+e(n.slice(1))}}function f(e,t={}){let n=t.split??(t.separateNumbers?o:a),r=t.prefixCharacters??``,i=t.suffixCharacters??``,s=0,c=e.length;for(;s<e.length;){let t=e.charAt(s);if(!r.includes(t))break;s++}for(;c>s;){let t=c-1,n=e.charAt(t);if(!i.includes(n))break;c=t}return[e.slice(0,s),n(e.slice(s,c)),e.slice(c)]}export{s as camelCase};

package/dist/exports/tests/node_modules/.bun/rate-limit-redis@4.3.1_f1fa5524233c9c60/node_modules/rate-limit-redis/dist/index.mjs

@@ -0,0 +1,25 @@
+const e={increment:`
+	      local windowMs = tonumber(ARGV[2])
+	      local resetOnChange = ARGV[1] == "1"
+
+	      local timeToExpire = redis.call("PTTL", KEYS[1])
+
+	      if timeToExpire <= 0 then
+	        redis.call("SET", KEYS[1], 1, "PX", windowMs)
+	        return { 1, windowMs }
+	      end
+
+	      local totalHits = redis.call("INCR", KEYS[1])
+
+	      if resetOnChange then
+	        redis.call("PEXPIRE", KEYS[1], windowMs)
+	        timeToExpire = windowMs
+	      end
+        
+	      return { totalHits, timeToExpire }
+		`.replaceAll(/^\s+/gm,``).trim(),get:`
+      local totalHits = redis.call("GET", KEYS[1])
+      local timeToExpire = redis.call("PTTL", KEYS[1])
+
+      return { totalHits, timeToExpire }
+		`.replaceAll(/^\s+/gm,``).trim()},t=e=>typeof e==`number`?e:Number.parseInt((e??``).toString(),10),n=e=>{if(!Array.isArray(e))throw TypeError(`Expected result to be array of values`);if(e.length!==2)throw Error(`Expected 2 replies, got ${e.length}`);let n=e[0]===!1?0:t(e[0]),r=t(e[1]);return{totalHits:n,resetTime:new Date(Date.now()+r)}};var r=class{sendCommand;prefix;resetExpiryOnChange;incrementScriptSha;getScriptSha;windowMs;constructor(e){if(typeof e!=`object`)throw TypeError(`rate-limit-redis: Error: options object is required`);if(`sendCommand`in e&&!(`sendCommandCluster`in e)){let t=e.sendCommand.bind(this);this.sendCommand=async({command:e})=>t(...e)}else if(!(`sendCommand`in e)&&`sendCommandCluster`in e)this.sendCommand=e.sendCommandCluster.bind(this);else throw Error(`rate-limit-redis: Error: options must include either sendCommand or sendCommandCluster (but not both)`);this.prefix=e.prefix??`rl:`,this.resetExpiryOnChange=e.resetExpiryOnChange??!1,this.incrementScriptSha=this.loadIncrementScript(),this.getScriptSha=this.loadGetScript()}async loadIncrementScript(t){let n=await this.sendCommand({key:t,isReadOnly:!1,command:[`SCRIPT`,`LOAD`,e.increment]});if(typeof n!=`string`)throw TypeError(`unexpected reply from redis client`);return n}async loadGetScript(t){let n=await this.sendCommand({key:t,isReadOnly:!1,command:[`SCRIPT`,`LOAD`,e.get]});if(typeof n!=`string`)throw TypeError(`unexpected reply from redis client`);return n}async retryableIncrement(e){let t=this.prefixKey(e),n=async()=>this.sendCommand({key:t,isReadOnly:!1,command:[`EVALSHA`,await this.incrementScriptSha,`1`,t,this.resetExpiryOnChange?`1`:`0`,this.windowMs.toString()]});try{return await n()}catch{return this.incrementScriptSha=this.loadIncrementScript(t),n()}}prefixKey(e){return`${this.prefix}${e}`}init(e){this.windowMs=e.windowMs}async get(e){let t=this.prefixKey(e),r,i=async()=>this.sendCommand({key:t,isReadOnly:!0,command:[`EVALSHA`,await this.getScriptSha,`1`,t]});try{r=await i()}catch{this.getScriptSha=this.loadGetScript(t),r=await i()}return n(r)}async increment(e){return n(await this.retryableIncrement(e))}async decrement(e){let t=this.prefixKey(e);await this.sendCommand({key:t,isReadOnly:!1,command:[`DECR`,t]})}async resetKey(e){let t=this.prefixKey(e);await this.sendCommand({key:t,isReadOnly:!1,command:[`DEL`,t]})}};export{r as RedisStore};

package/dist/exports/tests/packages/appos/src/api/app-context.d.mts

@@ -0,0 +1,115 @@
+import { AppContainer } from "./container.mjs";
+import { RequestMetadata } from "./middleware/request-logger.mjs";
+import { Request } from "ultimate-express";
+import { TFunction } from "i18next";
+import { Auth } from "better-auth";
+import { ApiKey } from "better-auth/plugins";
+
+//#region src/api/app-context.d.ts
+declare global {
+  namespace Express {
+    interface Locals {
+      /**
+       * The application container with services and dependencies.
+       */
+      container: AppContainer;
+    }
+    interface Request {
+      /**
+       * The API key, or null if not authenticated via API key.
+       */
+      apiKey: ApiKey | null;
+      /**
+       * The text direction for the detected language (e.g., "ltr" or "rtl").
+       */
+      dir: string;
+      /**
+       * The idempotency key provided in the request headers.
+       */
+      idempotencyKey?: string;
+      /**
+       * The detected language from the request's Accept-Language header.
+       */
+      language: string;
+      /**
+       * The list of supported languages.
+       */
+      languages: readonly string[];
+      /**
+       * Metadata about the request for logging purposes.
+       */
+      metadata: RequestMetadata;
+      /**
+       * Request body in raw bytes
+       */
+      rawBody?: Buffer;
+      /**
+       * The unique request ID for tracing purposes.
+       */
+      requestId: string;
+      /**
+       * The translation function for the detected language.
+       */
+      t: TFunction;
+    }
+  }
+}
+/**
+ * Session data from Better Auth's getSession().
+ */
+type SessionData = NonNullable<Awaited<ReturnType<Auth["api"]["getSession"]>>>;
+/**
+ * Unified context for tRPC, OpenAPI handlers, and services.
+ */
+interface AppContext {
+  /**
+   * The API key data, or null if not authenticated via API key.
+   */
+  apiKey: ApiKey | null;
+  /**
+   * Application container with services and dependencies.
+   */
+  container: AppContainer;
+  /**
+   * The incoming request object.
+   */
+  request: Request;
+  /**
+   * The current session, or null if not authenticated.
+   */
+  session: SessionData["session"] | null;
+  /**
+   * The current user, or null if not authenticated.
+   */
+  user: SessionData["user"] | null;
+}
+/**
+ * Options for creating an AppContext.
+ */
+interface DefineAppContextOpts {
+  /**
+   * The API key data, or null if not authenticated via API key.
+   */
+  apiKey: ApiKey | null;
+  /**
+   * Application container with services and dependencies.
+   */
+  container: AppContainer;
+  /**
+   * Set to true to fetch session (tRPC). False for API key auth (OpenAPI).
+   */
+  fetchSession?: boolean;
+  /**
+   * The incoming request object.
+   */
+  request: Request;
+}
+/**
+ * Creates a unified AppContext for tRPC and OpenAPI handlers.
+ *
+ * For tRPC (session auth): Pass fetchSession=true to fetch session from Better Auth.
+ * For OpenAPI (API key auth): Pass fetchSession=false (default), session will be null.
+ */
+declare function defineAppContext(opts: DefineAppContextOpts): Promise<AppContext>;
+//#endregion
+export { AppContext, DefineAppContextOpts, SessionData, defineAppContext };