@justscale/core 0.1.0

package/dist/builder/builder.js

@@ -0,0 +1,72 @@
+/**
+ * Builder Utilities
+ *
+ * Helper functions for creating bindings in the DI system.
+ */
+import { REPO_BINDING, SERVICE_BINDING, INSTANCE_BINDING } from './types.js';
+// ============================================================================
+// Token Creation Helpers
+// ============================================================================
+/**
+ * Bind a repository token to an implementation.
+ *
+ * This creates a binding for the DI system to wire up repositories.
+ */
+export function bindRepository(token, implementation) {
+    return {
+        [REPO_BINDING]: true,
+        token,
+        implementation,
+    };
+}
+/**
+ * Bind an abstract service token to a concrete implementation.
+ *
+ * This creates a binding for the DI system to wire up abstract services.
+ * Use this when you have an abstract class and want to specify which
+ * concrete implementation should be used.
+ *
+ * @example
+ * ```typescript
+ * import JustScale, { bindService } from '@justscale/core'
+ *
+ * JustScale()
+ *   .add(MemoryChannelBackend)
+ *   .add(bindService(AbstractChannelBackend, MemoryChannelBackend))
+ *   .build()
+ * ```
+ */
+export function bindService(abstractToken, implementation) {
+    return {
+        [SERVICE_BINDING]: true,
+        token: abstractToken,
+        implementation,
+    };
+}
+/**
+ * Bind an abstract service token to a pre-created instance.
+ *
+ * This creates a binding for the DI system to wire up abstract services
+ * to specific instances. Use this when you have an instance you want to
+ * share across the app.
+ *
+ * @example
+ * ```typescript
+ * import JustScale, { bindInstance } from '@justscale/core'
+ *
+ * const taskRepo = new InMemoryScheduledTaskRepository()
+ *
+ * JustScale()
+ *   .add(bindInstance(ScheduledTaskRepository, taskRepo))
+ *   .add(TaskController)
+ *   .build()
+ * ```
+ */
+export function bindInstance(abstractToken, instance) {
+    return {
+        [INSTANCE_BINDING]: true,
+        token: abstractToken,
+        instance,
+    };
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/builder/builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAU7E,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAyB,EACzB,cAAuB;IAEvB,OAAO;QACL,CAAC,YAAY,CAAC,EAAE,IAAI;QACpB,KAAK;QACL,cAAc;KACS,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CACzB,aAAsC,EACtC,cAAmC;IAEnC,OAAO;QACL,CAAC,eAAe,CAAC,EAAE,IAAI;QACvB,KAAK,EAAE,aAAa;QACpB,cAAc;KACc,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAC1B,aAA8B,EAC9B,QAAW;IAEX,OAAO;QACL,CAAC,gBAAgB,CAAC,EAAE,IAAI;QACxB,KAAK,EAAE,aAAa;QACpB,QAAQ;KACa,CAAC;AAC1B,CAAC"}

package/dist/builder/create-builder.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Route Builder Factory
+ *
+ * Provides the createBaseBuilder and createBuilderState functions
+ * for constructing route builders with middleware/guard execution steps.
+ */
+import type { z } from 'zod';
+import type { PermissionDefLike, RouteBuilder, UnresolvedStep } from './types.js';
+/**
+ * Internal state for building a route.
+ */
+export interface BuilderState {
+    /** Sequential steps - use and guard interleaved (may contain unresolved GuardDefs) */
+    steps: UnresolvedStep[];
+    /** Response schemas mapped by status code */
+    responseSchemas: Map<number, z.ZodType | null>;
+    /** Model types for path param → Reference transformation */
+    types?: Record<string, abstract new (...args: any[]) => any>;
+    /** Permission-scoped returns - populated via `.returns(status, schema, permission)` */
+    permissionReturns?: Array<{
+        status: number;
+        schema: z.ZodType | null;
+        permission: PermissionDefLike;
+    }>;
+}
+/**
+ * Create initial builder state.
+ */
+export declare function createBuilderState(): BuilderState;
+/**
+ * Create a base route builder.
+ * This provides the core use/guard/apply/returns/handle methods.
+ * Protocol-specific builders extend this.
+ */
+export declare function createBaseBuilder<TPath extends string, THandlerReturn = void | Promise<void>>(state: BuilderState, path: TPath): RouteBuilder<{}, unknown, never, TPath, unknown, THandlerReturn>;
+//# sourceMappingURL=create-builder.d.ts.map

package/dist/builder/create-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-builder.d.ts","sourceRoot":"","sources":["../../src/builder/create-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB,6CAA6C;IAC7C,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAC9C,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAA;IAC5D,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,KAAK,CAAC;QACxB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,CAAA;QACxB,UAAU,EAAE,iBAAiB,CAAA;KAC9B,CAAC,CAAA;CACH;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAKjD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC3F,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,KAAK,GACV,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,CAAC,CAmDlE"}

package/dist/builder/create-builder.js

@@ -0,0 +1,66 @@
+/**
+ * Route Builder Factory
+ *
+ * Provides the createBaseBuilder and createBuilderState functions
+ * for constructing route builders with middleware/guard execution steps.
+ */
+/**
+ * Create initial builder state.
+ */
+export function createBuilderState() {
+    return {
+        steps: [],
+        responseSchemas: new Map()
+    };
+}
+/**
+ * Create a base route builder.
+ * This provides the core use/guard/apply/returns/handle methods.
+ * Protocol-specific builders extend this.
+ */
+export function createBaseBuilder(state, path) {
+    const builder = {
+        use(middleware) {
+            state.steps.push({ type: 'use', fn: middleware });
+            return builder;
+        },
+        guard(check) {
+            state.steps.push({ type: 'guard', fn: check });
+            return builder;
+        },
+        apply(plugin) {
+            // Plugin transforms builder, adding its own steps
+            return plugin(builder);
+        },
+        returns(status, schema, permission) {
+            state.responseSchemas.set(status, schema ?? null);
+            if (permission) {
+                state.permissionReturns ??= [];
+                state.permissionReturns.push({
+                    status,
+                    schema: schema ?? null,
+                    permission,
+                });
+            }
+            return builder;
+        },
+        types(types) {
+            state.types = types;
+            return builder;
+        },
+        handle(handler) {
+            return {
+                path,
+                steps: [...state.steps],
+                responseSchemas: new Map(state.responseSchemas),
+                handler,
+                ...(state.types ? { types: state.types } : {}),
+                ...(state.permissionReturns && state.permissionReturns.length > 0
+                    ? { permissionReturns: [...state.permissionReturns] }
+                    : {}),
+            };
+        }
+    };
+    return builder;
+}
+//# sourceMappingURL=create-builder.js.map

package/dist/builder/create-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-builder.js","sourceRoot":"","sources":["../../src/builder/create-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,KAAK,EAAE,EAAE;QACT,eAAe,EAAE,IAAI,GAAG,EAAE;KAC3B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAmB,EACnB,IAAW;IAGX,MAAM,OAAO,GAA+C;QAC1D,GAAG,CAAC,UAAU;YACZ,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;YAClD,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,KAAK;YACT,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/C,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,MAAM;YACV,kDAAkD;YAClD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QAED,OAAO,CAAC,MAAc,EAAE,MAAkB,EAAE,UAA8B;YACxE,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;YAClD,IAAI,UAAU,EAAE,CAAC;gBACf,KAAK,CAAC,iBAAiB,KAAK,EAAE,CAAC;gBAC/B,KAAK,CAAC,iBAAiB,CAAC,IAAI,CAAC;oBAC3B,MAAM;oBACN,MAAM,EAAE,MAAM,IAAI,IAAI;oBACtB,UAAU;iBACX,CAAC,CAAC;YACL,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,KAAK;YACT,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;YACpB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,MAAM,CAAC,OAAO;YACZ,OAAO;gBACL,IAAI;gBACJ,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC;gBACvB,eAAe,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC;gBAC/C,OAAO;gBACP,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9C,GAAG,CAAC,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC;oBAC/D,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,GAAG,KAAK,CAAC,iBAAiB,CAAC,EAAE;oBACrD,CAAC,CAAC,EAAE,CAAC;aACR,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/builder/execute.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Route Execution Runtime
+ *
+ * Executes a route with sequential middleware and guard execution.
+ * Steps run in declaration order, with guards receiving stop() and
+ * middleware extending context via Object.assign.
+ */
+/** Minimal interface for routes that executeRoute can process. */
+interface ExecutableRoute {
+    steps: Array<{
+        type: 'use' | 'guard';
+        fn: unknown;
+    }>;
+    handler: (ctx: any) => any;
+}
+/**
+ * Run only the middleware/guard steps for a route, without calling the handler.
+ *
+ * Used by protocols (SSE, etc.) that need to enforce guards but then drive the
+ * handler themselves (e.g., an async generator that must stream back to a response).
+ *
+ * @param route - The finalized route definition (steps must be resolved)
+ * @param ctx - Mutable context shared between steps (extended in-place by use steps)
+ * @returns `true` if all steps passed, `false` if a guard denied the request.
+ */
+export declare function executeSteps(route: Pick<ExecutableRoute, 'steps'>, ctx: Record<string, unknown>): Promise<boolean>;
+/**
+ * Execute a route with the given context.
+ * Steps run sequentially in declaration order.
+ *
+ * @param route - The finalized route definition (steps must be resolved, not GuardDefs)
+ * @param ctx - Initial context (protocol provides res, req, params, etc.)
+ * @returns `true` if all steps passed and the handler ran, `false` if a guard stopped execution.
+ */
+export declare function executeRoute(route: ExecutableRoute, ctx: Record<string, unknown>): Promise<boolean>;
+export {};
+//# sourceMappingURL=execute.d.ts.map

package/dist/builder/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/builder/execute.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,kEAAkE;AAClE,UAAU,eAAe;IACvB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACrD,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,EACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,OAAO,CAAC,OAAO,CAAC,CAOlB"}

package/dist/builder/execute.js

@@ -0,0 +1,62 @@
+/**
+ * Route Execution Runtime
+ *
+ * Executes a route with sequential middleware and guard execution.
+ * Steps run in declaration order, with guards receiving stop() and
+ * middleware extending context via Object.assign.
+ */
+import { isStop, createStopFn } from './stop.js';
+/**
+ * Run only the middleware/guard steps for a route, without calling the handler.
+ *
+ * Used by protocols (SSE, etc.) that need to enforce guards but then drive the
+ * handler themselves (e.g., an async generator that must stream back to a response).
+ *
+ * @param route - The finalized route definition (steps must be resolved)
+ * @param ctx - Mutable context shared between steps (extended in-place by use steps)
+ * @returns `true` if all steps passed, `false` if a guard denied the request.
+ */
+export async function executeSteps(route, ctx) {
+    // Expose the route on the context so middleware/guards can introspect it.
+    ctx.__route = route;
+    const steps = route.steps ?? [];
+    for (const step of steps) {
+        const fn = step.fn;
+        if (typeof fn !== 'function') {
+            throw new Error('Route step has an unresolved dependency (GuardDef) — ' +
+                'route steps must be resolved before execution. ' +
+                'Ensure the route is registered via createController.');
+        }
+        if (step.type === 'use') {
+            const additions = await fn(ctx);
+            Object.assign(ctx, additions);
+        }
+        else {
+            const stop = createStopFn();
+            ctx.stop = stop;
+            const result = await fn(ctx);
+            delete ctx.stop;
+            if (isStop(result) || result === false) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Execute a route with the given context.
+ * Steps run sequentially in declaration order.
+ *
+ * @param route - The finalized route definition (steps must be resolved, not GuardDefs)
+ * @param ctx - Initial context (protocol provides res, req, params, etc.)
+ * @returns `true` if all steps passed and the handler ran, `false` if a guard stopped execution.
+ */
+export async function executeRoute(route, ctx) {
+    const passed = await executeSteps(route, ctx);
+    if (!passed)
+        return false;
+    // All steps passed - run handler
+    await route.handler(ctx);
+    return true;
+}
+//# sourceMappingURL=execute.js.map

package/dist/builder/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../src/builder/execute.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAQjD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAqC,EACrC,GAA4B;IAE5B,0EAA0E;IACzE,GAAW,CAAC,OAAO,GAAG,KAAK,CAAC;IAE7B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,uDAAuD;gBACvD,iDAAiD;gBACjD,sDAAsD,CACvD,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YACxB,MAAM,SAAS,GAAG,MAAO,EAAwB,CAAC,GAAG,CAAC,CAAC;YACvD,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;YAC3B,GAAW,CAAC,IAAI,GAAG,IAAI,CAAC;YACzB,MAAM,MAAM,GAAG,MAAO,EAAwB,CAAC,GAAU,CAAC,CAAC;YAC3D,OAAQ,GAAW,CAAC,IAAI,CAAC;YACzB,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBACvC,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAsB,EACtB,GAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAE1B,iCAAiC;IACjC,MAAM,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/builder/feature-builder.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Feature Builder V2
+ *
+ * Fluent builder for creating features with type-safe requirement tracking.
+ *
+ * @example
+ * ```typescript
+ * const AuthFeature = createFeatureBuilder()
+ *   .name('auth')
+ *   .requires(ModelRepository.of(User))
+ *   .requires(ModelRepository.of(Session))
+ *   .onStart(async ({ resolve }) => {
+ *     const auth = resolve(AuthService)
+ *     await auth.initialize()
+ *   })
+ *   .provides((b) => b
+ *     .add(AuthService)
+ *     .add(AuthController)
+ *   )
+ * ```
+ */
+import type { Builder, AnyToken, FeatureToken, FeatureMetadata, StartHook, StopHook } from './types.js';
+/**
+ * Fluent builder for creating features.
+ *
+ * Each `.requires()` call accumulates the requirement in the phantom type,
+ * enabling TypeScript to track what the feature needs.
+ *
+ * When requiring another Feature, that feature's provides become available
+ * to use in your `.provides()` callback.
+ *
+ * @typeParam TRequires - Tuple of required tokens (accumulated)
+ * @typeParam TAvailable - Tuple of tokens available from required features
+ */
+export interface FeatureBuilder<TRequires extends AnyToken[] = [], TAvailable extends AnyToken[] = []> {
+    /**
+     * Declare a dependency on a token or feature.
+     *
+     * The token must be provided before this feature is added to a builder.
+     * When requiring a Feature, that feature's provides become available.
+     *
+     * @example
+     * ```typescript
+     * createFeatureBuilder()
+     *   .requires(ModelRepository.of(User))
+     *   .requires(PgClient)
+     *   .requires(DatabaseFeature) // DatabaseFeature's provides are now available
+     * ```
+     */
+    requires<T extends AnyToken>(token: T): T extends FeatureToken<any, infer TFeatureProv extends AnyToken[]> ? FeatureBuilder<[...TRequires, T], [...TAvailable, ...TFeatureProv]> : FeatureBuilder<[...TRequires, T], TAvailable>;
+    /**
+     * Set a human-readable name for this feature.
+     *
+     * Used in error messages and debugging.
+     */
+    name(name: string): FeatureBuilder<TRequires, TAvailable>;
+    /**
+     * Add a lifecycle hook called when the cluster starts.
+     *
+     * @example
+     * ```typescript
+     * .onStart(async ({ resolve }) => {
+     *   const db = resolve(PgClient)
+     *   await db.connect()
+     * })
+     * ```
+     */
+    onStart(hook: StartHook): FeatureBuilder<TRequires, TAvailable>;
+    /**
+     * Add a lifecycle hook called when the cluster stops.
+     *
+     * @example
+     * ```typescript
+     * .onStop(async () => {
+     *   await cleanup()
+     * })
+     * ```
+     */
+    onStop(hook: StopHook): FeatureBuilder<TRequires, TAvailable>;
+    /**
+     * Define what this feature provides.
+     *
+     * The callback receives a builder that has all required tokens available
+     * (including provides from required features), and returns a builder with
+     * the provided components added.
+     *
+     * @example
+     * ```typescript
+     * .provides((b) => b
+     *   .add(AuthService)
+     *   .add(AuthController)
+     * )
+     * ```
+     */
+    provides<TProvides extends AnyToken[]>(fn: (builder: Builder<[...TRequires, ...TAvailable]>) => Builder<[...TRequires, ...TAvailable, ...TProvides]>): FeatureToken<TRequires, TProvides>;
+}
+/**
+ * Create a new feature builder.
+ *
+ * Features are reusable bundles of services and controllers that can be
+ * added to a cluster. They declare their requirements via `.requires()`
+ * and what they provide via `.provides()`.
+ *
+ * @example
+ * ```typescript
+ * // Simple feature with no requirements
+ * const LoggingFeature = createFeatureBuilder()
+ *   .provides((b) => b.add(LoggerService))
+ *
+ * // Feature with requirements
+ * const AuthFeature = createFeatureBuilder()
+ *   .name('auth')
+ *   .requires(ModelRepository.of(User))
+ *   .requires(ModelRepository.of(Session))
+ *   .provides((b) => b
+ *     .add(AuthService)
+ *     .add(SessionService)
+ *     .add(AuthController)
+ *   )
+ *
+ * // Feature with lifecycle hooks
+ * const DatabaseFeature = createFeatureBuilder()
+ *   .name('database')
+ *   .onStart(async ({ resolve }) => {
+ *     const client = resolve(PgClient)
+ *     await client.connect()
+ *   })
+ *   .onStop(async () => {
+ *     // cleanup
+ *   })
+ *   .provides((b) => b.add(PgClient))
+ * ```
+ */
+export declare function createFeatureBuilder(): FeatureBuilder<[], []>;
+/**
+ * Get the metadata from a feature token.
+ */
+export declare function getFeatureMetadata(feature: FeatureToken<any, any>): FeatureMetadata;
+/**
+ * Get the requirements from a feature token.
+ */
+export declare function getFeatureRequirements(feature: FeatureToken<any, any>): AnyToken[];
+/**
+ * Get the name from a feature token.
+ */
+export declare function getFeatureName(feature: FeatureToken<any, any>): string | undefined;
+//# sourceMappingURL=feature-builder.d.ts.map

package/dist/builder/feature-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-builder.d.ts","sourceRoot":"","sources":["../../src/builder/feature-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,SAAS,EACT,QAAQ,EACT,MAAM,YAAY,CAAC;AAOpB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc,CAC7B,SAAS,SAAS,QAAQ,EAAE,GAAG,EAAE,EACjC,UAAU,SAAS,QAAQ,EAAE,GAAG,EAAE;IAElC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,CAAC,SAAS,QAAQ,EACzB,KAAK,EAAE,CAAC,GACP,CAAC,SAAS,YAAY,CAAC,GAAG,EAAE,MAAM,YAAY,SAAS,QAAQ,EAAE,CAAC,GACjE,cAAc,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,GAAG,YAAY,CAAC,CAAC,GACnE,cAAc,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,CAAA;IAEjD;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;IAEzD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;IAE/D;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;IAE7D;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,SAAS,SAAS,QAAQ,EAAE,EACnC,EAAE,EAAE,CACF,OAAO,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EAAE,GAAG,UAAU,CAAC,CAAC,KAC5C,OAAO,CAAC,CAAC,GAAG,SAAS,EAAE,GAAG,UAAU,EAAE,GAAG,SAAS,CAAC,CAAC,GACxD,YAAY,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CACtC;AAyFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAAC,EAAE,EAAE,EAAE,CAAC,CAE7D;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GAC9B,eAAe,CAEjB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GAC9B,QAAQ,EAAE,CAEZ;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GAC9B,MAAM,GAAG,SAAS,CAEpB"}

package/dist/builder/feature-builder.js

@@ -0,0 +1,138 @@
+/**
+ * Feature Builder V2
+ *
+ * Fluent builder for creating features with type-safe requirement tracking.
+ *
+ * @example
+ * ```typescript
+ * const AuthFeature = createFeatureBuilder()
+ *   .name('auth')
+ *   .requires(ModelRepository.of(User))
+ *   .requires(ModelRepository.of(Session))
+ *   .onStart(async ({ resolve }) => {
+ *     const auth = resolve(AuthService)
+ *     await auth.initialize()
+ *   })
+ *   .provides((b) => b
+ *     .add(AuthService)
+ *     .add(AuthController)
+ *   )
+ * ```
+ */
+import { FEATURE_TOKEN, FEATURE_META } from './types.js';
+/**
+ * Feature builder implementation.
+ */
+class FeatureBuilderImpl {
+    state;
+    constructor(state = { requires: [] }) {
+        this.state = state;
+    }
+    requires(token) {
+        return new FeatureBuilderImpl({
+            ...this.state,
+            requires: [...this.state.requires, token],
+        });
+    }
+    name(name) {
+        return new FeatureBuilderImpl({
+            ...this.state,
+            name,
+        });
+    }
+    onStart(hook) {
+        return new FeatureBuilderImpl({
+            ...this.state,
+            onStart: hook,
+        });
+    }
+    onStop(hook) {
+        return new FeatureBuilderImpl({
+            ...this.state,
+            onStop: hook,
+        });
+    }
+    provides(fn) {
+        const metadata = {
+            name: this.state.name,
+            requires: this.state.requires,
+            onStart: this.state.onStart,
+            onStop: this.state.onStop,
+        };
+        // Create the feature function
+        const feature = ((builder) => {
+            return fn(builder);
+        });
+        // Attach metadata
+        Object.defineProperties(feature, {
+            [FEATURE_TOKEN]: { value: true, enumerable: false },
+            [FEATURE_META]: { value: metadata, enumerable: false },
+        });
+        return feature;
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new feature builder.
+ *
+ * Features are reusable bundles of services and controllers that can be
+ * added to a cluster. They declare their requirements via `.requires()`
+ * and what they provide via `.provides()`.
+ *
+ * @example
+ * ```typescript
+ * // Simple feature with no requirements
+ * const LoggingFeature = createFeatureBuilder()
+ *   .provides((b) => b.add(LoggerService))
+ *
+ * // Feature with requirements
+ * const AuthFeature = createFeatureBuilder()
+ *   .name('auth')
+ *   .requires(ModelRepository.of(User))
+ *   .requires(ModelRepository.of(Session))
+ *   .provides((b) => b
+ *     .add(AuthService)
+ *     .add(SessionService)
+ *     .add(AuthController)
+ *   )
+ *
+ * // Feature with lifecycle hooks
+ * const DatabaseFeature = createFeatureBuilder()
+ *   .name('database')
+ *   .onStart(async ({ resolve }) => {
+ *     const client = resolve(PgClient)
+ *     await client.connect()
+ *   })
+ *   .onStop(async () => {
+ *     // cleanup
+ *   })
+ *   .provides((b) => b.add(PgClient))
+ * ```
+ */
+export function createFeatureBuilder() {
+    return new FeatureBuilderImpl();
+}
+// ============================================================================
+// Feature Utilities
+// ============================================================================
+/**
+ * Get the metadata from a feature token.
+ */
+export function getFeatureMetadata(feature) {
+    return feature[FEATURE_META];
+}
+/**
+ * Get the requirements from a feature token.
+ */
+export function getFeatureRequirements(feature) {
+    return feature[FEATURE_META].requires;
+}
+/**
+ * Get the name from a feature token.
+ */
+export function getFeatureName(feature) {
+    return feature[FEATURE_META].name;
+}
+//# sourceMappingURL=feature-builder.js.map

package/dist/builder/feature-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-builder.js","sourceRoot":"","sources":["../../src/builder/feature-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAUH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA8GzD;;GAEG;AACH,MAAM,kBAAkB;IAKF;IAApB,YAAoB,QAA6B,EAAE,QAAQ,EAAE,EAAE,EAAE;QAA7C,UAAK,GAAL,KAAK,CAAwC;IAAG,CAAC;IAErE,QAAQ,CACN,KAAQ;QAIR,OAAO,IAAI,kBAAkB,CAAC;YAC5B,GAAG,IAAI,CAAC,KAAK;YACb,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC;SAC1C,CAAQ,CAAC;IACZ,CAAC;IAED,IAAI,CAAC,IAAY;QACf,OAAO,IAAI,kBAAkB,CAAC;YAC5B,GAAG,IAAI,CAAC,KAAK;YACb,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CAAC,IAAe;QACrB,OAAO,IAAI,kBAAkB,CAAC;YAC5B,GAAG,IAAI,CAAC,KAAK;YACb,OAAO,EAAE,IAAI;SACd,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,IAAc;QACnB,OAAO,IAAI,kBAAkB,CAAC;YAC5B,GAAG,IAAI,CAAC,KAAK;YACb,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;IACL,CAAC;IAED,QAAQ,CACN,EAEyD;QAEzD,MAAM,QAAQ,GAAoB;YAChC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ;YAC7B,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO;YAC3B,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;SAC1B,CAAC;QAEF,8BAA8B;QAC9B,MAAM,OAAO,GAAG,CAAC,CAAC,OAA2B,EAAE,EAAE;YAC/C,OAAO,EAAE,CAAC,OAAc,CAAC,CAAC;QAC5B,CAAC,CAAkD,CAAC;QAEpD,kBAAkB;QAClB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE;YAC/B,CAAC,aAAa,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE;YACnD,CAAC,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE;SACvD,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAED,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,kBAAkB,EAAE,CAAC;AAClC,CAAC;AAED,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA+B;IAE/B,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA+B;IAE/B,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA+B;IAE/B,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC;AACpC,CAAC"}

package/dist/builder/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Builder V2 Module
+ *
+ * Fluent builder API for creating apps with type-safe dependency tracking.
+ *
+ * @example
+ * ```typescript
+ * import JustScale, { bindRepository } from '@justscale/core'
+ * import { ModelRepository } from '@justscale/core/models'
+ *
+ * const app = JustScale()
+ *   .add(PgClient)
+ *   .add(bindRepository(ModelRepository.of(User), PgUser))
+ *   .add(UserService)
+ *   .build()
+ * ```
+ */
+export type { Token, AnyToken, Component, Builder, BuiltCluster, ServeOptions, RepositoryBinding, ServiceBinding, InstanceBinding, FeatureToken, FeatureMetadata, BuilderCallback, StartHook, StopHook, ProvidesOf, RequiresOf, RemoveFromTuple, } from './types.js';
+export { isServiceDef, isControllerDef, isRepositoryBinding, isServiceBinding, isInstanceBinding, isFeatureToken, isBuilderCallback, isComponentArray, FEATURE_TOKEN, FEATURE_META, REPO_BINDING, SERVICE_BINDING, INSTANCE_BINDING, } from './types.js';
+export { bindRepository, bindService, bindInstance } from './builder.js';
+export { createFeatureBuilder, getFeatureMetadata, getFeatureRequirements, getFeatureName, } from './feature-builder.js';
+export type { FeatureBuilder } from './feature-builder.js';
+export { DependencyError, validateDependencies, buildDependencyGraph, findMissingDependencies, getTokenDescription, registerPluginProvides, getPluginProvides, registerImplicitService, getImplicitServices, } from './validation.js';
+export type { MissingDependency, DependencyGraph, } from './validation.js';
+export { topologicalSort, CycleError, } from './sort.js';
+export type { Stop } from './stop.js';
+export { isStop, createStopFn } from './stop.js';
+export type { ExtractMiddlewareAdded, ExtractAddedFromMiddleware, ExtractStepDeps, ResponseEntry, ExtractStatuses, ExtractBodyForStatus, Step, UnresolvedStep, RouteDef, RouteBuilder, BuilderPlugin, PermissionDefLike, PermOf, BodyOf, NameOf, PermEntries, ToPermissionVariant, PermissionVariants, } from './types.js';
+export { PLUGIN_SYMBOL, isPlugin, createPlugin } from './plugin.js';
+export type { BuilderState } from './create-builder.js';
+export { createBuilderState, createBaseBuilder } from './create-builder.js';
+export { executeRoute, executeSteps } from './execute.js';
+export { query } from './plugins/query.js';
+export { ValidationErrorSchema } from './plugins/validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builder/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,YAAY,EACV,KAAK,EACL,QAAQ,EACR,SAAS,EACT,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,eAAe,EACf,eAAe,EACf,SAAS,EACT,QAAQ,EACR,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGzE,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,eAAe,EACf,UAAU,GACX,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGjD,YAAY,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,EACf,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,IAAI,EACJ,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,aAAa,EAEb,iBAAiB,EACjB,MAAM,EACN,MAAM,EACN,MAAM,EACN,WAAW,EACX,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGpE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG1D,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}