@justscale/core 0.1.0

package/dist/core/middleware.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Middleware & Guard Definitions
+ *
+ * Provides middleware and guard types with dependency injection support.
+ */
+import type { ServiceToken, ResolvedDeps } from './service.js';
+/**
+ * Middleware function that can add properties to the context.
+ * Returns an object that will be merged into the context.
+ */
+export type Middleware<TIn, TOut> = (ctx: TIn) => TOut | Promise<TOut>;
+/**
+ * Guard function that gates access to a route.
+ * Returns true to allow, false to block (short-circuit).
+ * Can also throw an error for custom error handling.
+ */
+export type Guard<TContext> = (ctx: TContext) => boolean | Promise<boolean>;
+/** Runtime marker for middleware definitions */
+export declare const MIDDLEWARE_DEF_MARKER: unique symbol;
+/** Runtime marker for guard definitions */
+export declare const GUARD_DEF_MARKER: unique symbol;
+/**
+ * Middleware definition with dependency injection.
+ * Like ServiceDef, but produces a middleware function.
+ *
+ * @example
+ * ```typescript
+ * const AuthMiddleware = createMiddleware({
+ *   inject: { users: UserService, tokens: TokenService },
+ *   handler: ({ users, tokens }) => async (ctx) => {
+ *     const user = await tokens.validate(ctx.signals.token);
+ *     return { user };  // Adds { user: User } to context
+ *   }
+ * });
+ * ```
+ */
+export interface MiddlewareDef<TAdded extends object = object, TDeps extends Record<string, ServiceToken> = Record<string, ServiceToken>> {
+    readonly __kind: typeof MIDDLEWARE_DEF_MARKER;
+    readonly deps: TDeps;
+    readonly factory: (deps: ResolvedDeps<TDeps>) => Middleware<any, TAdded>;
+}
+/**
+ * Guard definition with dependency injection.
+ * Like ServiceDef, but produces a guard function.
+ *
+ * @example
+ * ```typescript
+ * const IsAdmin = createGuard({
+ *   inject: { permissions: PermissionService },
+ *   check: ({ permissions }) => async (ctx) => {
+ *     return permissions.isAdmin(ctx.user);
+ *   }
+ * });
+ * ```
+ */
+export interface GuardDef<TDeps extends Record<string, ServiceToken> = Record<string, ServiceToken>> {
+    readonly __kind: typeof GUARD_DEF_MARKER;
+    readonly deps: TDeps;
+    readonly factory: (deps: ResolvedDeps<TDeps>) => Guard<any>;
+}
+/** Check if value is a MiddlewareDef */
+export declare function isMiddlewareDef(value: unknown): value is MiddlewareDef<any, any>;
+/** Check if value is a GuardDef */
+export declare function isGuardDef(value: unknown): value is GuardDef<any>;
+/**
+ * Create a middleware with typed dependencies.
+ *
+ * @example
+ * ```typescript
+ * const AuthMiddleware = createMiddleware({
+ *   inject: { tokens: TokenService },
+ *   handler: ({ tokens }) => async (ctx) => {
+ *     const user = await tokens.validate(ctx.signals.token);
+ *     return { user };
+ *   }
+ * });
+ * ```
+ */
+export declare function createMiddleware<const TDeps extends Record<string, ServiceToken>, TAdded extends object>(config: {
+    inject: TDeps;
+    handler: (deps: ResolvedDeps<TDeps>) => Middleware<any, TAdded>;
+}): MiddlewareDef<TAdded, TDeps>;
+/**
+ * Create a guard with typed dependencies.
+ *
+ * @example
+ * ```typescript
+ * const IsAdmin = createGuard({
+ *   inject: { perms: PermissionService },
+ *   check: ({ perms }) => (ctx) => perms.isAdmin(ctx.user)
+ * });
+ * ```
+ */
+export declare function createGuard<const TDeps extends Record<string, ServiceToken>>(config: {
+    inject: TDeps;
+    check: (deps: ResolvedDeps<TDeps>) => Guard<any>;
+}): GuardDef<TDeps>;
+/** Unresolved middleware - can be a function or a definition */
+export type UnresolvedMiddleware = Middleware<any, any> | MiddlewareDef<any, any>;
+/** Unresolved guard - can be a function or a definition */
+export type UnresolvedGuard = Guard<any> | GuardDef<any>;
+/** Extract the "added" type from a MiddlewareDef */
+export type MiddlewareAdded<T> = T extends MiddlewareDef<infer A, any> ? A : never;
+/** Input to .use() - either a function or a definition */
+export type MiddlewareInput<TContext, TAdded extends object> = Middleware<TContext, TAdded> | MiddlewareDef<TAdded, any>;
+/** Input to .guard() - either a function or a definition */
+export type GuardInput<TContext> = Guard<TContext> | GuardDef<any>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/core/middleware.d.ts.map

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

package/dist/core/middleware.js

@@ -0,0 +1,60 @@
+/**
+ * Middleware & Guard Definitions
+ *
+ * Provides middleware and guard types with dependency injection support.
+ */
+// ============================================================================
+// Runtime Markers (declared first so interface __kind types can reference them)
+// ============================================================================
+/** Runtime marker for middleware definitions */
+export const MIDDLEWARE_DEF_MARKER = Symbol('@justscale/middleware');
+/** Runtime marker for guard definitions */
+export const GUARD_DEF_MARKER = Symbol('@justscale/guard');
+/** Check if value is a MiddlewareDef */
+export function isMiddlewareDef(value) {
+    return typeof value === 'object' && value !== null && value.__kind === MIDDLEWARE_DEF_MARKER;
+}
+/** Check if value is a GuardDef */
+export function isGuardDef(value) {
+    return typeof value === 'object' && value !== null && value.__kind === GUARD_DEF_MARKER;
+}
+/**
+ * Create a middleware with typed dependencies.
+ *
+ * @example
+ * ```typescript
+ * const AuthMiddleware = createMiddleware({
+ *   inject: { tokens: TokenService },
+ *   handler: ({ tokens }) => async (ctx) => {
+ *     const user = await tokens.validate(ctx.signals.token);
+ *     return { user };
+ *   }
+ * });
+ * ```
+ */
+export function createMiddleware(config) {
+    return {
+        __kind: MIDDLEWARE_DEF_MARKER,
+        deps: config.inject,
+        factory: config.handler,
+    };
+}
+/**
+ * Create a guard with typed dependencies.
+ *
+ * @example
+ * ```typescript
+ * const IsAdmin = createGuard({
+ *   inject: { perms: PermissionService },
+ *   check: ({ perms }) => (ctx) => perms.isAdmin(ctx.user)
+ * });
+ * ```
+ */
+export function createGuard(config) {
+    return {
+        __kind: GUARD_DEF_MARKER,
+        deps: config.inject,
+        factory: config.check,
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/core/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/core/middleware.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqBH,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAE/E,gDAAgD;AAChD,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAErE,2CAA2C;AAC3C,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAoD3D,wCAAwC;AACxC,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAa,CAAC,MAAM,KAAK,qBAAqB,CAAC;AACxG,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAa,CAAC,MAAM,KAAK,gBAAgB,CAAC;AACnG,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAG9B,MAGD;IACC,OAAO;QACL,MAAM,EAAE,qBAAqB;QAC7B,IAAI,EAAE,MAAM,CAAC,MAAM;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAEzB,MAGD;IACC,OAAO;QACL,MAAM,EAAE,gBAAgB;QACxB,IAAI,EAAE,MAAM,CAAC,MAAM;QACnB,OAAO,EAAE,MAAM,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC"}

package/dist/core/openapi-methods.d.ts

@@ -0,0 +1,61 @@
+/**
+ * OpenAPI method registry - protocols self-describe how their route
+ * methods surface in an OpenAPI 3.1 document.
+ *
+ * Each protocol package that wants to appear in OpenAPI specs registers
+ * its method names on module load:
+ *
+ * ```ts
+ * // @justscale/http
+ * import { registerOpenApiMethod } from '@justscale/core';
+ * for (const m of ['GET', 'POST', 'PUT', ...]) {
+ *   registerOpenApiMethod(m, { httpMethod: m.toLowerCase() });
+ * }
+ *
+ * // @justscale/sse
+ * registerOpenApiMethod('SSE', {
+ *   httpMethod: 'get',
+ *   responseContentType: 'text/event-stream',
+ * });
+ * ```
+ *
+ * The OpenAPI generator (`@justscale/feature-openapi`) consults this
+ * registry to decide (a) whether a route is documentable at all -
+ * CLI / WebSocket / Event routes have no standard OpenAPI
+ * representation, so they register nothing and get filtered out; and
+ * (b) what HTTP method to emit under `paths` and which response
+ * content type to advertise.
+ *
+ * Core knows nothing about HTTP or SSE directly - it just holds a
+ * registry. Protocol packages own their own entries.
+ */
+/**
+ * How a protocol's runtime method value maps onto OpenAPI 3.1 shape.
+ */
+export interface OpenApiMethodMapping {
+    /**
+     * OpenAPI operation verb - one of `get`, `post`, `put`, `patch`,
+     * `delete`, `head`, `options`, `trace`. SSE-style protocols can
+     * declare `httpMethod: 'get'` to be emitted as a GET with a custom
+     * response content type.
+     */
+    readonly httpMethod: string;
+    /**
+     * Optional content type for the emitted response. Defaults to
+     * `application/json` when unset. SSE sets this to
+     * `text/event-stream`; future streaming-newline protocols might
+     * use `application/x-ndjson`.
+     */
+    readonly responseContentType?: string;
+}
+/**
+ * Register a protocol method name as OpenAPI-visible.
+ * Duplicate registrations for the same method are ignored (first-win)
+ * so two protocols claiming the same name can't step on each other.
+ */
+export declare function registerOpenApiMethod(method: string, mapping: OpenApiMethodMapping): void;
+/** Resolve a runtime method value to its OpenAPI emission shape. */
+export declare function getOpenApiMethodMapping(method: unknown): OpenApiMethodMapping | undefined;
+/** Snapshot of every registered method (for tests / debug). */
+export declare function getRegisteredOpenApiMethods(): ReadonlyMap<string, OpenApiMethodMapping>;
+//# sourceMappingURL=openapi-methods.d.ts.map

package/dist/core/openapi-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-methods.d.ts","sourceRoot":"","sources":["../../src/core/openapi-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAIN;AAED,oEAAoE;AACpE,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,GACd,oBAAoB,GAAG,SAAS,CAGlC;AAED,+DAA+D;AAC/D,wBAAgB,2BAA2B,IAAI,WAAW,CACxD,MAAM,EACN,oBAAoB,CACrB,CAEA"}

package/dist/core/openapi-methods.js

@@ -0,0 +1,53 @@
+/**
+ * OpenAPI method registry - protocols self-describe how their route
+ * methods surface in an OpenAPI 3.1 document.
+ *
+ * Each protocol package that wants to appear in OpenAPI specs registers
+ * its method names on module load:
+ *
+ * ```ts
+ * // @justscale/http
+ * import { registerOpenApiMethod } from '@justscale/core';
+ * for (const m of ['GET', 'POST', 'PUT', ...]) {
+ *   registerOpenApiMethod(m, { httpMethod: m.toLowerCase() });
+ * }
+ *
+ * // @justscale/sse
+ * registerOpenApiMethod('SSE', {
+ *   httpMethod: 'get',
+ *   responseContentType: 'text/event-stream',
+ * });
+ * ```
+ *
+ * The OpenAPI generator (`@justscale/feature-openapi`) consults this
+ * registry to decide (a) whether a route is documentable at all -
+ * CLI / WebSocket / Event routes have no standard OpenAPI
+ * representation, so they register nothing and get filtered out; and
+ * (b) what HTTP method to emit under `paths` and which response
+ * content type to advertise.
+ *
+ * Core knows nothing about HTTP or SSE directly - it just holds a
+ * registry. Protocol packages own their own entries.
+ */
+const registry = new Map();
+/**
+ * Register a protocol method name as OpenAPI-visible.
+ * Duplicate registrations for the same method are ignored (first-win)
+ * so two protocols claiming the same name can't step on each other.
+ */
+export function registerOpenApiMethod(method, mapping) {
+    if (!registry.has(method)) {
+        registry.set(method, mapping);
+    }
+}
+/** Resolve a runtime method value to its OpenAPI emission shape. */
+export function getOpenApiMethodMapping(method) {
+    if (typeof method !== 'string')
+        return undefined;
+    return registry.get(method);
+}
+/** Snapshot of every registered method (for tests / debug). */
+export function getRegisteredOpenApiMethods() {
+    return registry;
+}
+//# sourceMappingURL=openapi-methods.js.map

package/dist/core/openapi-methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-methods.js","sourceRoot":"","sources":["../../src/core/openapi-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAsBH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;AAEzD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,OAA6B;IAE7B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;AACH,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,uBAAuB,CACrC,MAAe;IAEf,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACjD,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,2BAA2B;IAIzC,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/core/plugin.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @justscale/core/plugin
+ *
+ * Base route factory system. This module provides the extensible
+ * infrastructure for route factories. HTTP methods, Datastar routes,
+ * and other route types are implemented as plugins.
+ *
+ * @example
+ * ```typescript
+ * import type { RouteHandler, RouteDef } from "@justscale/core/plugin";
+ *
+ * declare module "@justscale/core/plugin" {
+ *   interface RouteFactories<TDeps> {
+ *     MyRoute(path: string, handler: RouteHandler<TDeps>): RouteDef<TDeps>;
+ *   }
+ * }
+ *
+ * import { registerRouteFactory } from "@justscale/core/plugin";
+ * registerRouteFactory("MyRoute", MyRoute);
+ * ```
+ */
+import type { CliFactory } from '../cli/types.js';
+import type { Middleware, Guard, MiddlewareDef, GuardDef } from './middleware.js';
+/**
+ * Extract parameter names from a path pattern.
+ * "/users/:id" → { id: string }
+ * "/users/:userId/posts/:postId" → { userId: string; postId: string }
+ */
+export type ExtractParams<Path extends string> = Path extends `${string}:${infer Param}/${infer Rest}` ? {
+    [K in Param]: string;
+} & ExtractParams<`/${Rest}`> : Path extends `${string}:${infer Param}` ? {
+    [K in Param]: string;
+} : {};
+/** Flatten intersection types for cleaner display */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Method metadata - describes characteristics of a route method.
+ * Used by testing utilities, OpenAPI generation, etc.
+ */
+export interface MethodMetadata {
+    /** Transport type (e.g., 'http', 'cli', 'event') */
+    transport: string;
+    /** Whether this method typically has a request body */
+    hasBody?: boolean;
+    /** Whether this method is idempotent */
+    idempotent?: boolean;
+}
+/**
+ * Extensible route method interface.
+ * Transports extend this via module augmentation with metadata:
+ *
+ * @example
+ * ```typescript
+ * // In @justscale/http
+ * declare module "@justscale/core" {
+ *   interface SupportedMethods {
+ *     GET: { transport: 'http'; hasBody: false; idempotent: true };
+ *     POST: { transport: 'http'; hasBody: true; idempotent: false };
+ *   }
+ * }
+ * ```
+ */
+export interface SupportedMethods {
+    CLI: {
+        transport: 'cli';
+        hasBody: false;
+    };
+    GET: {
+        transport: 'http';
+        hasBody: false;
+        idempotent: true;
+    };
+    POST: {
+        transport: 'http';
+        hasBody: true;
+        idempotent: false;
+    };
+    PUT: {
+        transport: 'http';
+        hasBody: true;
+        idempotent: true;
+    };
+    DELETE: {
+        transport: 'http';
+        hasBody: false;
+        idempotent: true;
+    };
+    PATCH: {
+        transport: 'http';
+        hasBody: true;
+        idempotent: false;
+    };
+    EVENT: {
+        transport: 'event';
+    };
+    SUBSCRIBE: {
+        transport: 'subscribe';
+    };
+    WS: {
+        transport: 'websocket';
+        hasBody: false;
+        idempotent: false;
+    };
+    PROCEDURE: {
+        transport: 'procedure';
+        hasBody: true;
+        idempotent: false;
+    };
+    SCHEDULED_TASK: {
+        transport: 'scheduled-task';
+    };
+}
+/**
+ * Get metadata for a specific method.
+ * @example
+ * type PostMeta = GetMethodMetadata<'POST'>; // { transport: 'http'; hasBody: true; ... }
+ */
+export type GetMethodMetadata<M extends RouteMethod> = SupportedMethods[M];
+/**
+ * Check if a method has a request body.
+ * @example
+ * type PostHasBody = MethodHasBody<'POST'>; // true
+ * type GetHasBody = MethodHasBody<'GET'>;   // false
+ */
+export type MethodHasBody<M extends RouteMethod> = SupportedMethods[M] extends {
+    hasBody: infer H;
+} ? H : false;
+/**
+ * Get all methods for a specific transport.
+ * @example
+ * type HttpMethods = MethodsForTransport<'http'>; // 'GET' | 'POST' | 'PUT' | ...
+ */
+export type MethodsForTransport<T extends string> = {
+    [K in RouteMethod]: SupportedMethods[K] extends {
+        transport: T;
+    } ? K : never;
+}[RouteMethod];
+/**
+ * All registered route methods.
+ * Transports add methods via module augmentation on SupportedMethods.
+ */
+export type RouteMethod = keyof SupportedMethods;
+/** Base context available to all routes before middleware */
+export interface BaseContext<TDeps = Record<string, unknown>, TParams = Record<string, string>> {
+    deps: TDeps;
+    params: Prettify<TParams>;
+}
+/**
+ * Route context interface - extensible by plugins.
+ * Plugins can augment this interface to add transport-specific properties.
+ */
+export interface RouteContext<TDeps = Record<string, unknown>, TParams = Record<string, string>> extends BaseContext<TDeps, TParams> {
+}
+/** A route handler function */
+export type RouteHandler<TDeps = Record<string, unknown>, TParams = Record<string, string>> = (ctx: RouteContext<TDeps, TParams>) => void | Promise<void>;
+/**
+ * Builder for composing routes with middleware and guards.
+ * Each .use() call accumulates the context type.
+ *
+ * @example
+ * ```typescript
+ * // With raw functions
+ * Get("/users/:id")
+ *   .use(authMiddleware)
+ *   .guard(isAuthenticated)
+ *   .handle(({ params, user, stream }) => { ... })
+ *
+ * // With DI-enabled definitions
+ * Get("/users/:id")
+ *   .use(AuthMiddleware)  // MiddlewareDef
+ *   .guard(IsAdmin)       // GuardDef
+ *   .handle(({ params, user, stream }) => { ... })
+ * ```
+ */
+export interface RouteBuilder<TDeps, TParams, TContext, TPath extends string = string, TBody = unknown, TResponse = unknown> {
+    /**
+     * Add middleware that extends the context.
+     * Accepts either a middleware function or a MiddlewareDef (with DI).
+     */
+    use<TAdded extends object>(middleware: Middleware<TContext, TAdded>): RouteBuilder<TDeps, TParams, Prettify<TContext & TAdded>, TPath, TBody, TResponse>;
+    use<TAdded extends object>(middleware: MiddlewareDef<TAdded, any>): RouteBuilder<TDeps, TParams, Prettify<TContext & TAdded>, TPath, TBody, TResponse>;
+    /**
+     * Add a guard that gates access to the route.
+     * Accepts either a guard function or a GuardDef (with DI).
+     */
+    guard(check: Guard<TContext>): RouteBuilder<TDeps, TParams, TContext, TPath, TBody, TResponse>;
+    guard(check: GuardDef<any>): RouteBuilder<TDeps, TParams, TContext, TPath, TBody, TResponse>;
+    /**
+     * Set the final handler for the route.
+     * Receives the accumulated context from all middleware.
+     */
+    handle(handler: (ctx: TContext) => void | Promise<void>): any;
+}
+/**
+ * Extensible interface for route factories.
+ * Plugins extend via declaration merging on "@justscale/core/plugin".
+ */
+export interface RouteFactories<TDeps> {
+    /** CLI route factory - built-in since CLI is part of core */
+    Cli: CliFactory<TDeps>;
+}
+/** Register a route factory (for plugins) */
+export declare function registerRouteFactory(name: string, factory: Function): void;
+/** Create all registered route factories with proper typing */
+export declare function createRouteFactories<TDeps>(): RouteFactories<TDeps>;
+export type { Middleware, Guard, MiddlewareDef, GuardDef, UnresolvedMiddleware, UnresolvedGuard, } from './middleware.js';
+//# sourceMappingURL=plugin.d.ts.map

package/dist/core/plugin.d.ts.map

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

package/dist/core/plugin.js

@@ -0,0 +1,36 @@
+/**
+ * @justscale/core/plugin
+ *
+ * Base route factory system. This module provides the extensible
+ * infrastructure for route factories. HTTP methods, Datastar routes,
+ * and other route types are implemented as plugins.
+ *
+ * @example
+ * ```typescript
+ * import type { RouteHandler, RouteDef } from "@justscale/core/plugin";
+ *
+ * declare module "@justscale/core/plugin" {
+ *   interface RouteFactories<TDeps> {
+ *     MyRoute(path: string, handler: RouteHandler<TDeps>): RouteDef<TDeps>;
+ *   }
+ * }
+ *
+ * import { registerRouteFactory } from "@justscale/core/plugin";
+ * registerRouteFactory("MyRoute", MyRoute);
+ * ```
+ */
+/** Registry for route factory implementations */
+const routeFactoryRegistry = new Map();
+/** Register a route factory (for plugins) */
+export function registerRouteFactory(name, factory) {
+    routeFactoryRegistry.set(name, factory);
+}
+/** Create all registered route factories with proper typing */
+export function createRouteFactories() {
+    const factories = {};
+    for (const [name, factory] of routeFactoryRegistry) {
+        factories[name] = factory;
+    }
+    return factories;
+}
+//# sourceMappingURL=plugin.js.map

package/dist/core/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/core/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAwMH,iDAAiD;AACjD,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAoB,CAAC;AAEzD,6CAA6C;AAC7C,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,OAAiB;IAClE,oBAAoB,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,oBAAoB;IAClC,MAAM,SAAS,GAA6B,EAAE,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC;QACnD,SAAS,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IAC5B,CAAC;IACD,OAAO,SAA6C,CAAC;AACvD,CAAC"}

package/dist/core/scope-bridge.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Scope-switching bridge - wraps a service resolved in a parent scope so
+ * every method call re-enters that parent scope via `runWithContainer`.
+ * Used by sub-app composition to share services across container boundaries
+ * without leaking async context.
+ */
+import { Container, type ServiceToken } from './service.js';
+/**
+ * Resolve `token` from `parentContainer` and wrap it so every method call
+ * runs inside the parent's async scope. The returned proxy shares state
+ * with the original instance.
+ */
+export declare function createScopedBridge<T extends object>(parentContainer: Container, token: ServiceToken<T>): Promise<T>;
+/**
+ * Synchronous variant for cases where you've already resolved the
+ * instance and just need scope switching on top.
+ */
+export declare function wrapWithScope<T extends object>(target: T, parentContainer: Container): T;
+//# sourceMappingURL=scope-bridge.d.ts.map

package/dist/core/scope-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-bridge.d.ts","sourceRoot":"","sources":["../../src/core/scope-bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EACvD,eAAe,EAAE,SAAS,EAC1B,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC5C,MAAM,EAAE,CAAC,EACT,eAAe,EAAE,SAAS,GACzB,CAAC,CAaH"}

package/dist/core/scope-bridge.js

@@ -0,0 +1,34 @@
+/**
+ * Scope-switching bridge - wraps a service resolved in a parent scope so
+ * every method call re-enters that parent scope via `runWithContainer`.
+ * Used by sub-app composition to share services across container boundaries
+ * without leaking async context.
+ */
+import { runWithContainer } from './context.js';
+/**
+ * Resolve `token` from `parentContainer` and wrap it so every method call
+ * runs inside the parent's async scope. The returned proxy shares state
+ * with the original instance.
+ */
+export async function createScopedBridge(parentContainer, token) {
+    const target = (await parentContainer.resolve(token));
+    return wrapWithScope(target, parentContainer);
+}
+/**
+ * Synchronous variant for cases where you've already resolved the
+ * instance and just need scope switching on top.
+ */
+export function wrapWithScope(target, parentContainer) {
+    return new Proxy(target, {
+        get(obj, prop, receiver) {
+            const value = Reflect.get(obj, prop, receiver);
+            if (typeof value !== 'function')
+                return value;
+            // Preserve the original function reference identity; only the call is wrapped.
+            return function (...args) {
+                return runWithContainer(parentContainer, () => value.apply(obj, args));
+            };
+        },
+    });
+}
+//# sourceMappingURL=scope-bridge.js.map

package/dist/core/scope-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-bridge.js","sourceRoot":"","sources":["../../src/core/scope-bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,eAA0B,EAC1B,KAAsB;IAEtB,MAAM,MAAM,GAAG,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,CAAM,CAAC;IAC3D,OAAO,aAAa,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAS,EACT,eAA0B;IAE1B,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;QACvB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ;YACrB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC/C,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,OAAO,KAAK,CAAC;YAC9C,+EAA+E;YAC/E,OAAO,UAAyB,GAAG,IAAe;gBAChD,OAAO,gBAAgB,CAAC,eAAe,EAAE,GAAG,EAAE,CAC3C,KAAsC,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CACzD,CAAC;YACJ,CAAC,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}