@capixjs/core 0.1.0-alpha.1

package/dist/capability.js

@@ -0,0 +1,268 @@
+/**
+ * capability.ts — the core capability primitive
+ * Depends on: errors.ts, context.ts, guards.ts, zod
+ */
+import { runInputGuards } from './guards.js';
+const CAPABILITY_BRAND = Symbol.for('capix.Capability');
+const QUERY_PREFIXES = ['get', 'find', 'fetch', 'read', 'list', 'search', 'filter', 'me', 'status', 'health', 'count', 'check'];
+const MUTATION_PREFIXES = ['create', 'add', 'new'];
+const UPDATE_PREFIXES = ['update', 'edit', 'patch', 'modify'];
+const REPLACE_PREFIXES = ['replace', 'set', 'put'];
+const DELETE_PREFIXES = ['delete', 'remove', 'destroy', 'cancel'];
+/** Infers capability intent from its key name in the parent group. */
+export function inferIntent(key) {
+    const lower = key.toLowerCase();
+    for (const p of QUERY_PREFIXES) {
+        if (lower.startsWith(p))
+            return 'query';
+    }
+    for (const p of MUTATION_PREFIXES) {
+        if (lower.startsWith(p))
+            return 'mutation';
+    }
+    for (const p of UPDATE_PREFIXES) {
+        if (lower.startsWith(p))
+            return 'update';
+    }
+    for (const p of REPLACE_PREFIXES) {
+        if (lower.startsWith(p))
+            return 'replace';
+    }
+    for (const p of DELETE_PREFIXES) {
+        if (lower.startsWith(p))
+            return 'delete';
+    }
+    return 'mutation';
+}
+function makeCapability(base) {
+    const cap = base;
+    const rawFn = base._fn;
+    // Attach methods as non-enumerable properties so spread in chaining doesn't copy them,
+    // and so enhancers returning { ...cap, resolve: wrappedFn } can set a plain enumerable
+    // resolve that enhance() picks up as the new _fn.
+    Object.defineProperties(base, {
+        // _resolverOnly: raw resolver, no guards. Used by the execution engine (guards already ran).
+        // Also called by enhancers to wrap the resolver without re-running guards.
+        _resolverOnly: {
+            value: rawFn,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        // resolve: runs all guards, then calls the raw resolver.
+        // Accepts BaseContext — safe for composition from any calling context.
+        // Non-async fast path when no guards: avoids extra microtask tick so fake-timer
+        // tests and hot-path callers see no overhead vs the old direct-fn assignment.
+        resolve: {
+            value: (input, ctx) => {
+                if (base.guards.length === 0 && base.inputGuards.length === 0) {
+                    const r = rawFn(input, ctx);
+                    return (r instanceof Promise ? r : Promise.resolve(r));
+                }
+                const run = async () => {
+                    for (const guard of base.guards) {
+                        const gr = guard(ctx);
+                        if (gr !== undefined && gr !== null && typeof gr.then === 'function') {
+                            await gr;
+                        }
+                    }
+                    if (base.inputGuards.length > 0) {
+                        await runInputGuards(base.inputGuards, input, ctx);
+                    }
+                    return rawFn(input, ctx);
+                };
+                return run();
+            },
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        guard: {
+            value(g) {
+                return makeCapability({
+                    ...base,
+                    guards: [...base.guards, g],
+                });
+            },
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        inputGuard: {
+            value(g) {
+                return makeCapability({
+                    ...base,
+                    inputGuards: [...base.inputGuards, g],
+                });
+            },
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        enhance: {
+            value(e) {
+                const enhanced = e(cap);
+                // enhanced.resolve is the plain enumerable property set by the enhancer:
+                //   (cap) => ({ ...cap, resolve: wrappedFn })
+                // This wrappedFn calls cap._resolverOnly internally, so guards don't double-run.
+                // We use it as the new raw resolver for the returned capability.
+                return makeCapability({
+                    ...base,
+                    _fn: enhanced.resolve,
+                });
+            },
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        output: {
+            value(schema) {
+                return makeCapability({
+                    ...base,
+                    outputSchema: schema,
+                });
+            },
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+    });
+    return cap;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function capability(...args) {
+    const [first, second, thirdArg] = args;
+    const isZodSchema = first !== null &&
+        typeof first === 'object' &&
+        '_def' in first;
+    if (!isZodSchema) {
+        // No-schema overloads: capability(resolver) | capability(resolver, intent)
+        const explicitIntent = typeof second === 'string' ? second : undefined;
+        return makeCapability({
+            _capix: true,
+            [CAPABILITY_BRAND]: true,
+            name: '(unnamed)',
+            _input: undefined,
+            _output: undefined,
+            _context: undefined,
+            inputSchema: null,
+            outputSchema: null,
+            guards: [],
+            inputGuards: [],
+            _intentExplicit: explicitIntent !== undefined,
+            intent: explicitIntent ?? 'mutation',
+            _skipValidation: false,
+            _fn: first,
+        });
+    }
+    // Schema overloads: capability(schema, resolver) | capability(schema, resolver, intent)
+    const thirdIntent = typeof thirdArg === 'string' ? thirdArg : undefined;
+    return makeCapability({
+        _capix: true,
+        [CAPABILITY_BRAND]: true,
+        name: '(unnamed)',
+        _input: undefined,
+        _output: undefined,
+        _context: undefined,
+        inputSchema: first,
+        outputSchema: null,
+        guards: [],
+        inputGuards: [],
+        _intentExplicit: thirdIntent !== undefined,
+        intent: thirdIntent ?? 'mutation',
+        _skipValidation: false,
+        _fn: second,
+    });
+}
+// ---------------------------------------------------------------------------
+// isCapability
+// ---------------------------------------------------------------------------
+/** Returns true for values created by capability(). Plain objects with _capix: true return false. */
+export function isCapability(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[CAPABILITY_BRAND] === true);
+}
+/**
+ * Flattens a nested capability tree into a registry Map keyed by dot-path names.
+ *
+ * `createServer` calls this automatically — use it directly only when building
+ * custom transports or tooling that needs the registry before the server starts.
+ *
+ * Each capability is named from its path in the tree (`users.getUser`, `posts.create`).
+ * Capabilities with an empty `z.object({})` input schema have `_skipValidation` set so
+ * the execution engine bypasses Zod entirely for those routes.
+ *
+ * @throws {Error} If any key is not a camelCase identifier (letters and digits only,
+ *   must start with a letter). Dashes, underscores, and leading digits are rejected.
+ */
+const VALID_KEY = /^[a-zA-Z][a-zA-Z0-9]*$/;
+export function compileRegistry(tree, prefix = '') {
+    const map = new Map();
+    for (const [key, value] of Object.entries(tree)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (!VALID_KEY.test(key)) {
+            throw new Error(`[capix] Invalid capability key: "${key}" at path "${path}". ` +
+                `Keys must be camelCase identifiers (letters and numbers only, ` +
+                `starting with a letter). Examples: getUser, listOrders, createPost.`);
+        }
+        if (isCapability(value)) {
+            // True when inputSchema is z.object({}) — execution engine skips safeParse entirely.
+            const skipVal = value.inputSchema !== null &&
+                'shape' in value.inputSchema &&
+                typeof value.inputSchema.shape === 'object' &&
+                value.inputSchema.shape !== null &&
+                Object.keys(value.inputSchema.shape).length === 0;
+            // Create a named copy by building a fresh capability base with the correct name.
+            // _resolverOnly is the raw resolver (= base._fn on the original capability).
+            const base = {
+                _capix: true,
+                [CAPABILITY_BRAND]: true,
+                name: path,
+                _input: undefined,
+                _output: undefined,
+                _context: undefined,
+                inputSchema: value.inputSchema,
+                outputSchema: value.outputSchema,
+                guards: value.guards,
+                inputGuards: value.inputGuards,
+                intent: value.intent,
+                _intentExplicit: value._intentExplicit,
+                _skipValidation: skipVal,
+                // _resolverOnly === base._fn on the original capability (direct reference, no wrapping).
+                _fn: value._resolverOnly,
+            };
+            map.set(path, makeCapability(base));
+        }
+        else {
+            const nested = compileRegistry(value, path);
+            for (const [nestedPath, cap] of nested) {
+                map.set(nestedPath, cap);
+            }
+        }
+    }
+    return map;
+}
+// eslint-disable-next-line @typescript-eslint/no-namespace
+(function (capability) {
+    /**
+     * Returns a `capability()` factory with TContext pre-bound.
+     * The resolver's `ctx` parameter is inferred as TContext without annotation,
+     * and guards typed for TContext are accepted without the `any` escape hatch.
+     *
+     * @example
+     * const appCap = capability.withContext<AppContext>();
+     * const getUser = appCap(
+     *   z.object({ id: z.string() }),
+     *   async (input, ctx) => {  // ctx: AppContext — no annotation needed
+     *     if (!ctx.user) throw Errors.Unauthorized();
+     *     return db.users.find(input.id);
+     *   },
+     * ).guard(mustBeAuthenticated);
+     */
+    function withContext() {
+        return capability;
+    }
+    capability.withContext = withContext;
+})(capability || (capability = {}));
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,35 @@
+/**
+ * context.ts — request context types and builder
+ * No dependencies.
+ */
+/** Raw request data passed to buildContext. */
+export type RawRequest = {
+    readonly headers: Record<string, string | string[] | undefined>;
+    readonly method: string;
+    readonly url: string;
+    readonly signal: AbortSignal;
+    /**
+     * Raw request body bytes, populated by the transport when a body is present.
+     * Useful for HMAC webhook signature verification where re-serializing parsed
+     * JSON is not safe (key order and whitespace may differ).
+     * Undefined for GET/HEAD requests and empty-body requests.
+     */
+    readonly rawBody?: Buffer;
+};
+/** Minimum fields guaranteed on every context object. */
+export type BaseContext = {
+    readonly requestId: string;
+};
+/** A function that builds the application context from a raw request. */
+export type ContextBuilder<TContext extends BaseContext = BaseContext> = (req: RawRequest) => TContext | Promise<TContext>;
+/**
+ * Pass-through function for type inference and readability.
+ * Use this to define your buildContext function with full type checking.
+ */
+export declare function defineContext<TContext extends BaseContext>(builder: ContextBuilder<TContext>): ContextBuilder<TContext>;
+/**
+ * Case-insensitive header lookup.
+ * Returns the first value if the header is an array.
+ */
+export declare function getHeader(req: RawRequest, name: string): string | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,cAAc,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,IAAI,CACvE,GAAG,EAAE,UAAU,KACZ,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,SAAS,WAAW,EACxD,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,GAChC,cAAc,CAAC,QAAQ,CAAC,CAE1B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU3E"}

package/dist/context.js

@@ -0,0 +1,28 @@
+/**
+ * context.ts — request context types and builder
+ * No dependencies.
+ */
+/**
+ * Pass-through function for type inference and readability.
+ * Use this to define your buildContext function with full type checking.
+ */
+export function defineContext(builder) {
+    return builder;
+}
+/**
+ * Case-insensitive header lookup.
+ * Returns the first value if the header is an array.
+ */
+export function getHeader(req, name) {
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(req.headers)) {
+        if (key.toLowerCase() === lower) {
+            const val = req.headers[key];
+            if (val === undefined)
+                return undefined;
+            return Array.isArray(val) ? val[0] : val;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2BH;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAiC;IAEjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAe,EAAE,IAAY;IACrD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,KAAK,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YACxC,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC3C,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/enhancers.d.ts

@@ -0,0 +1,92 @@
+/**
+ * enhancers.ts — built-in capability enhancers
+ * Depends on: capability.ts
+ */
+import type { Enhancer } from './capability.js';
+/** Pass-through for type inference. */
+export declare function defineEnhancer(fn: Enhancer): Enhancer;
+/** Logs capability name, duration, and outcome. Falls back to console if ctx has no logger. */
+export declare const withLogging: Enhancer;
+/** In-memory cache. Key = capabilityName:JSON(input). TTL in seconds. */
+export declare function withCache(ttlSeconds: number): Enhancer;
+/** Rejects if the resolver exceeds the given milliseconds. */
+export declare function withTimeout(ms: number): Enhancer;
+/** Retries on non-FrameworkError failures with exponential backoff. */
+export declare function withRetry(maxAttempts: number, delayMs?: number): Enhancer;
+export type RateLimitOptions = {
+    readonly limit: number;
+    readonly windowMs: number;
+    /**
+     * Derives the rate limit key from input and context.
+     *
+     * WARNING: Defaults to the capability name — a GLOBAL limit shared across all callers.
+     * For production use, always provide a keyFn to limit per-user or per-IP:
+     *
+     * @example Per-user rate limit
+     * withRateLimit({ limit: 100, windowMs: 60_000, keyFn: (_input, ctx) => (ctx as AppContext).user?.id ?? 'anon' })
+     *
+     * @example Per-IP rate limit
+     * withRateLimit({ limit: 10, windowMs: 60_000, keyFn: (_input, ctx) => (ctx as AppContext).ip ?? 'unknown' })
+     */
+    readonly keyFn?: (input: unknown, ctx: unknown) => string;
+};
+/** Sliding-window in-memory rate limiter. Throws 429 when limit exceeded. */
+export declare function withRateLimit(options: RateLimitOptions): Enhancer;
+export type RollbackFn = () => unknown;
+/**
+ * Extends a context type with the `onRollback` method added by {@link withRollback}.
+ * Use this to type capabilities that need compensation actions.
+ *
+ * @example
+ * const cap = capability(schema, async (input, ctx: WithRollback<AppContext>) => {
+ *   ctx.onRollback(() => cleanup());
+ * }).enhance(withRollback);
+ */
+export type WithRollback<T> = T & {
+    readonly onRollback: (fn: RollbackFn) => void;
+};
+/**
+ * Adds explicit rollback support to a capability.
+ *
+ * Use ctx.onRollback(fn) to register compensation actions that run in reverse
+ * order if the resolver throws after one or more steps have already executed.
+ *
+ * This is NOT a database transaction. It does not provide atomicity,
+ * isolation, or durability. For real transactions, use your database's
+ * transaction API directly inside the resolver.
+ *
+ * Use this for: in-memory stores, multi-step operations where each step can
+ * be independently compensated (undone).
+ *
+ * @example
+ * export const checkout = cap(z.object({}), async (_, ctx) => {
+ *   const order = ctx.db.orders.create({ ... });
+ *   ctx.onRollback(() => ctx.db.orders.delete(order.id));
+ *
+ *   ctx.db.inventory.decrement(item.id);
+ *   ctx.onRollback(() => ctx.db.inventory.increment(item.id));
+ *
+ *   return order;
+ * }).enhance(withRollback);
+ */
+export declare const withRollback: Enhancer;
+export interface MetricsCollector {
+    increment(name: string, tags?: Record<string, string>): void;
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+}
+/** Metrics collector that logs to console. */
+export declare const consoleMetricsCollector: MetricsCollector;
+/** Wraps a capability to emit duration and success/error metrics. */
+export declare function withMetrics(collector: MetricsCollector): Enhancer;
+export type CircuitBreakerOptions = {
+    readonly failureThreshold: number;
+    readonly successThreshold: number;
+    readonly timeoutMs: number;
+};
+/**
+ * Circuit breaker with closed/open/half-open states.
+ * State is closure-captured per capability application.
+ * FrameworkErrors do not count toward the failure threshold.
+ */
+export declare function withCircuitBreaker(options: CircuitBreakerOptions): Enhancer;
+//# sourceMappingURL=enhancers.d.ts.map

package/dist/enhancers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhancers.d.ts","sourceRoot":"","sources":["../src/enhancers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,iBAAiB,CAAC;AAI/D,uCAAuC;AACvC,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,GAAG,QAAQ,CAErD;AAED,+FAA+F;AAC/F,eAAO,MAAM,WAAW,EAiBjB,QAAQ,CAAC;AAEhB,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAgBtD;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAqBhD;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,SAAM,GAAG,QAAQ,CAoBtE;AAMD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CAC3D,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,QAAQ,CAgCjE;AAMD,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC;AAEvC;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG;IAChC,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,IAAI,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,YAAY,EAsBlB,QAAQ,CAAC;AAMhB,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC7E;AAED,8CAA8C;AAC9C,eAAO,MAAM,uBAAuB,EAAE,gBAOrC,CAAC;AAEF,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,SAAS,EAAE,gBAAgB,GAAG,QAAQ,CAkBjE;AAMD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAMF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,qBAAqB,GAAG,QAAQ,CA+C3E"}