@stone-js/resources 0.8.9 → 0.8.11

package/dist/index.js

@@ -1,6 +1,147 @@
-import { hasMetadata, getMetadata, setClassMetadata, classDecoratorLegacyWrapper, addBlueprint, methodDecoratorLegacyWrapper, addMetadata } from '@stone-js/core';
+import { RuntimeError, hasMetadata, getMetadata, classDecoratorLegacyWrapper, setMetadata, SERVICE_KEY, addBlueprint, methodDecoratorLegacyWrapper, addMetadata } from '@stone-js/core';
 import { cloneValue } from '@stone-js/config';
 
+/**
+ * Runs a schema and reports what it said.
+ *
+ * This module reads schemas; it does not validate requests, own engines, or keep a registry — so it
+ * carries its own reader rather than depending on a validation module to project data. The dialects
+ * it accepts are public specifications, not one library's API: Standard Schema first, then the
+ * `safeParse`/`parse` shape, then a plain `validate`. An application writes its schemas once and both
+ * sides of the boundary read them.
+ *
+ * Substitutable: pass your own {@link IContractChecker} and this one steps aside.
+ */
+class ContractChecker {
+    /**
+     * Factory.
+     *
+     * @returns A checker.
+     */
+    static create() {
+        return new this();
+    }
+    /**
+     * Run a schema against a value.
+     *
+     * @param schema - The contract.
+     * @param data - What the resource produced.
+     * @returns Whether it holds, the parsed value, and what failed.
+     * @throws {TypeError} When the value is not a schema this can run, because guessing would mean
+     *                     projecting unchecked data while reporting success.
+     */
+    check(schema, data) {
+        if (this.isStandard(schema)) {
+            return this.fromStandard(schema, data);
+        }
+        if (this.hasSafeParse(schema)) {
+            return this.fromSafeParse(schema, data);
+        }
+        if (this.hasValidate(schema)) {
+            return this.fromValidate(schema, data);
+        }
+        if (this.hasParse(schema)) {
+            return this.fromParse(schema, data);
+        }
+        throw new TypeError('A resource schema must be runnable: a Standard Schema (Zod, Valibot, ArkType and others), or ' +
+            'something exposing `safeParse`, `parse` or `validate`. Reporting success on a value this cannot ' +
+            'run would mean projecting unchecked data, which is the one thing a contract must never do.');
+    }
+    /**
+     * Read a Standard Schema result.
+     *
+     * The synchronous path only: a schema whose validation is asynchronous returns a promise, and a
+     * promise is not a result. Saying so beats treating it as one, which is how `[object Promise]`
+     * reaches a response body.
+     *
+     * @param schema - The schema.
+     * @param data - The value.
+     * @returns The outcome.
+     */
+    fromStandard(schema, data) {
+        const result = schema['~standard'].validate(data);
+        if (result instanceof Promise) {
+            throw new TypeError('This resource schema validates asynchronously, which a projection cannot consume. Use the ' +
+                'synchronous form of your schema, or supply a checker that awaits it.');
+        }
+        const issues = result.issues;
+        return issues === undefined || issues.length === 0
+            ? { success: true, value: result.value }
+            : { success: false, issues: issues.map((issue) => this.toIssue(issue)) };
+    }
+    /**
+     * Read a `safeParse` result (the Zod-like shape).
+     *
+     * @param schema - The schema.
+     * @param data - The value.
+     * @returns The outcome.
+     */
+    fromSafeParse(schema, data) {
+        const result = schema.safeParse(data);
+        return result.success === true
+            ? { success: true, value: result.data }
+            : { success: false, issues: (result.error?.issues ?? []).map((issue) => this.toIssue(issue)) };
+    }
+    /**
+     * Read a native `validate` result: already the shape this module reports.
+     *
+     * @param schema - The schema.
+     * @param data - The value.
+     * @returns The outcome.
+     */
+    fromValidate(schema, data) {
+        const result = schema.validate(data);
+        return result?.success === true
+            ? { success: true, value: result.value }
+            : { success: false, issues: (result?.issues ?? []).map((issue) => this.toIssue(issue)) };
+    }
+    /**
+     * Read a throwing `parse`.
+     *
+     * @param schema - The schema.
+     * @param data - The value.
+     * @returns The outcome.
+     */
+    fromParse(schema, data) {
+        try {
+            return { success: true, value: schema.parse(data) };
+        }
+        catch (error) {
+            const issues = error?.issues ?? [{ message: String(error?.message ?? error), path: [] }];
+            return { success: false, issues: issues.map((issue) => this.toIssue(issue)) };
+        }
+    }
+    /**
+     * Normalise one issue, whatever dialect reported it.
+     *
+     * @param issue - The raw issue.
+     * @returns The issue.
+     */
+    toIssue(issue) {
+        const path = Array.isArray(issue.path)
+            // Standard Schema paths may carry segment objects rather than plain keys.
+            ? issue.path.map((segment) => (typeof segment === 'object' && segment !== null ? segment.key : segment))
+            : [];
+        return { message: issue.message ?? 'Invalid value', path };
+    }
+    /** @param schema - The candidate. @returns Whether it speaks Standard Schema. */
+    isStandard(schema) {
+        return typeof schema?.['~standard']?.validate === 'function';
+    }
+    /** @param schema - The candidate. @returns Whether it exposes `safeParse`. */
+    hasSafeParse(schema) {
+        return typeof schema?.safeParse === 'function';
+    }
+    /** @param schema - The candidate. @returns Whether it exposes `validate`. */
+    hasValidate(schema) {
+        return typeof schema?.validate === 'function';
+    }
+    /** @param schema - The candidate. @returns Whether it exposes `parse`. */
+    hasParse(schema) {
+        return typeof schema?.parse === 'function';
+    }
+}
+
 /**
  * Returns a copy of `object` without any `undefined` values (so conditional fields simply vanish).
  *
@@ -63,88 +204,205 @@ function applyFields(output, fields) {
     return fields !== undefined && fields.length > 0 ? only(clean, fields) : clean;
 }
 /**
- * Builds a {@link ResourceContext} from an incoming event's `fields` and `include` query
- * parameters (comma-separated). Agnostic: the event only needs a `get(key)` method.
+ * Build a {@link ResourceContext} from an incoming event.
+ *
+ * The parameter names are configuration, not convention: an API that already answers `?view=` or
+ * `?only=` keeps its own vocabulary instead of gaining a second one. Defaults are `fields`, `include`
+ * and `view`.
+ *
+ * The authenticated principal is read too, because deciding what a caller may see is the most common
+ * reason two callers get different shapes — and a resource that cannot see who is asking has to be
+ * told by the handler, which is exactly the plumbing this module exists to remove.
+ *
+ * Agnostic: the event only needs `get(key)`.
  *
  * @param event - Anything with `get(key)` (an `IncomingHttpEvent`, a URL search wrapper, …).
+ * @param blueprint - The blueprint carrying the parameter names, when there is one.
  * @param extra - Extra context to merge in.
  * @returns The resource context.
  */
-function contextFromEvent(event, extra = {}) {
+function contextFromEvent(event, blueprint, extra = {}) {
+    const names = blueprint?.get('stone.resources.params', {}) ?? {};
+    const fragment = event.get(names.fragment ?? 'view', '');
     return {
         ...extra,
-        fields: splitCsv(event.get('fields', '')),
-        include: splitCsv(event.get('include', ''))
+        event,
+        // `getUser()` and not `get('user')`: the principal is set through a resolver, not as metadata, so
+        // the generic accessor never reaches it. Duck-typed, because the kernel is agnostic and an event
+        // without a user simply has no such method.
+        principal: event.getUser?.(),
+        fields: splitCsv(event.get(names.fields ?? 'fields', '')),
+        include: splitCsv(event.get(names.include ?? 'include', '')),
+        fragment: fragment.length > 0 ? fragment : undefined
     };
 }
 /**
- * Splits a comma-separated string into a trimmed, non-empty list (or `undefined` when empty).
+ * Split a comma-separated string into a trimmed, non-empty list (or `undefined` when empty).
  *
  * @param value - The CSV string.
  * @returns The list, or `undefined`.
  */
 function splitCsv(value) {
-    const parts = value.split(',').map((part) => part.trim()).filter((part) => part.length > 0);
+    const parts = String(value).split(',').map((part) => part.trim()).filter((part) => part.length > 0);
     return parts.length > 0 ? parts : undefined;
 }
 
 /**
- * Base API resource — the declarative way to shape what your domain exposes.
+ * Raised when what a handler produced does not match the schema its resource published.
  *
- * Extend it and implement {@link Resource.toArray} to map a model to its public shape. Everything
- * else (sparse fieldsets, dropping conditional fields, collections, envelopes) is handled for you.
- * A resource is decoupled from controllers and platform-agnostic: the same resource shapes data on
- * the backend and on the frontend.
+ * This is a server-side fault, deliberately. The resource's schema is a promise made to every caller
+ * and to the published contract; data that breaks it means the application is about to answer
+ * something it documented it would not. Returning it anyway is the failure — a client cannot detect
+ * it, and a consumer generated from the contract will break on a field that was supposed to be there.
  *
- * @example
- * ```ts
- * class UserResource extends Resource<User> {
- *   toArray (user: User, ctx: ResourceContext) {
- *     return {
- *       id: user.id,
- *       name: user.name,
- *       email: this.when(ctx.self === true, user.email),
- *       posts: this.whenIncluded(ctx, 'posts', () => postResource.collection(user.posts))
- *     }
- *   }
- * }
- * ```
+ * It fires on a genuine breach, not on a difference: a schema strips what it does not describe, so
+ * extra fields are simply not exposed. Reaching this means something the contract requires is missing
+ * or has the wrong type.
  */
+class ResourceContractError extends RuntimeError {
+    /** What failed, so a log says which field rather than "validation failed". */
+    issues;
+    /**
+     * @param message - What went wrong.
+     * @param options - Additional error options, including the issues.
+     */
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = 'ResourceContractError';
+        this.issues = options.issues ?? [];
+    }
+}
+
 class Resource {
+    checker;
+    onViolation;
     /**
-     * Transform one model, applying the requested sparse fieldset and dropping undefined fields.
+     * @param dependencies - Auto-wired services.
+     *
+     * One name, bound by this module's own blueprint, so the container resolves it like any other service
+     * and this constructor reads it plainly. That is the whole point: a dependency read off a container
+     * that never bound it is not optional, it throws, which is what made every container-resolved
+     * resource fail. The answer was to register the checker, not to test for its presence.
+     *
+     * One name and no more, because destructuring reads each one: a resource must not have to know
+     * which services happen to be bound. The violation policy is configuration, and it travels with the
+     * request in the context, from `stone.resources.onViolation`. Substituting the dialect is a matter
+     * of binding `contractChecker` yourself.
+     */
+    constructor({ contractChecker } = {}) {
+        this.checker = contractChecker ?? ContractChecker.create();
+        this.onViolation = 'throw';
+    }
+    /**
+     * Project one model.
+     *
+     * The order is the design: complete the data, choose the contract the caller asked for, hold the
+     * result against it, then narrow. Validation happens *before* narrowing, so the promise is checked
+     * against everything the resource produced rather than against whatever survived a query parameter.
      *
      * @param model - The domain model.
      * @param context - The resource context.
-     * @returns The filtered public shape.
+     * @returns The projected output.
+     * @throws {ResourceContractError} When the data breaks the contract and the policy is `throw`.
      */
-    item(model, context = {}) {
-        return applyFields(this.toArray(model, context), context.fields);
+    async item(model, context = {}) {
+        const data = this.data !== undefined ? await this.data(model, context) : model;
+        const schema = await this.schemaFor(context);
+        const projected = await this.project(data, schema, context);
+        return applyFields(projected, context.fields);
     }
     /**
-     * Transform a collection of models.
+     * Project a collection.
+     *
+     * Sequential rather than concurrent: `data()` may reach a database or an API, and a hundred models
+     * turning into a hundred simultaneous calls is a denial of service an application performs on
+     * itself. A resource that wants concurrency batches inside its own `data()`, where it knows the cost.
      *
      * @param models - The domain models.
      * @param context - The resource context.
-     * @returns The transformed collection.
+     * @returns The projected collection.
      */
-    collection(models, context = {}) {
-        return models.map((model) => this.item(model, context));
+    async collection(models, context = {}) {
+        const out = [];
+        for (const model of models) {
+            out.push(await this.item(model, context));
+        }
+        return out;
     }
     /**
-     * Wrap a model or a collection in a `{ data, meta }` envelope.
+     * Project into a `{ data, meta }` envelope.
      *
      * @param models - A model or a collection.
      * @param context - The resource context.
      * @param meta - Optional metadata (pagination, counts, …).
      * @returns The envelope.
      */
-    response(models, context = {}, meta) {
-        const data = Array.isArray(models) ? this.collection(models, context) : this.item(models, context);
+    async response(models, context = {}, meta) {
+        const data = Array.isArray(models)
+            ? await this.collection(models, context)
+            : await this.item(models, context);
         return meta === undefined ? { data } : { data, meta };
     }
     /**
-     * Include a value only when `condition` is truthy (otherwise the field is dropped).
+     * The schema to hold this projection against: the requested fragment when the resource exposes one,
+     * the full contract otherwise.
+     *
+     * An unknown fragment falls back to the full contract rather than failing. A caller guessing
+     * `?view=nonsense` is asking a question, not attacking: answering the documented shape is more
+     * useful than a 500, and the fragments a resource exposes are published in the contract anyway.
+     *
+     * @param context - The resource context.
+     * @returns The schema.
+     */
+    async schemaFor(context) {
+        const name = context.fragment;
+        if (name !== undefined && this.fragments !== undefined) {
+            const available = await this.fragments(context);
+            if (available[name] !== undefined) {
+                return available[name];
+            }
+        }
+        return this.schema(context);
+    }
+    /**
+     * Hold the data against the contract, and return what the contract describes.
+     *
+     * The schema is the projection: its parsed value is the output, so a field the contract does not
+     * mention is not exposed, whatever the model gains later.
+     *
+     * @param data - The completed data.
+     * @param schema - The contract.
+     * @param context - The resource context.
+     * @returns The projected value.
+     * @throws {ResourceContractError} When the data breaks the contract and the policy is `throw`.
+     */
+    async project(data, schema, context) {
+        // From the context first, so an application may hand a projection its own dialect for one call;
+        // otherwise this module's own reader, which is why exposing data needs no validation module.
+        const checker = context.checker ?? this.checker;
+        const result = checker.check(schema, data);
+        if (result.success) {
+            return result.value;
+        }
+        const issues = result.issues ?? [];
+        const detail = issues
+            .map((issue) => `${issue.path.length > 0 ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+            .join('; ');
+        const message = `${this.constructor.name} produced data that does not match the contract it publishes: ${detail}. ` +
+            'The response was not sent, because a caller cannot detect a broken contract and a consumer ' +
+            'generated from it would break on the field that is missing.';
+        // Configured per application, and per projection when a caller of `item()` wants to override it.
+        const policy = context.onViolation ?? this.onViolation;
+        if (policy === 'warn') {
+            // Availability over integrity, chosen explicitly by configuration: the caller still gets what
+            // the schema could parse, and the breach is on the record.
+            console.warn(`[@stone-js/resources] ${message}`);
+            return data;
+        }
+        throw new ResourceContractError(message, { issues, metadata: { context } });
+    }
+    /**
+     * Include a value only when `condition` holds (otherwise the field is dropped).
      *
      * @param condition - Whether to include the value.
      * @param value - The value, or a lazy factory (only evaluated when included).
@@ -157,7 +415,7 @@ class Resource {
         return typeof value === 'function' ? value() : value;
     }
     /**
-     * Include a value only when the relation was requested via `context.include`.
+     * Include a value only when the relation was requested through `context.include`.
      *
      * @param context - The resource context.
      * @param name - The relation name.
@@ -170,25 +428,58 @@ class Resource {
 }
 
 /**
- * The imperative/functional way to define a resource — a plain transform function instead of a
- * class. Returns a full {@link Resource} (so you still get `item`/`collection`/`response` and
- * sparse fieldsets for free).
+ * The imperative way to define a resource: an object instead of a class.
+ *
+ * Parity is the rule, so this declares exactly what a class declares and gets exactly what a class
+ * gets. It needs nothing injected: this module reads schemas with its own checker.
  *
- * @param transform - Maps a model to its public shape.
+ * @param definition - The schema, and optionally fragments and a `data()` hook.
+ * @param dependencies - Optional explicit services, for a resource used outside a request.
  * @returns A resource.
  *
  * @example
  * ```ts
- * const userResource = defineResource<User>((user) => ({ id: user.id, name: user.name }))
- * userResource.collection(users, { fields: ['id'] })
+ * export const userResource = defineResource<User>({
+ *   schema: z.object({ id: z.number(), name: z.string() }),
+ *   fragments: { summary: z.object({ id: z.number() }) },
+ *   data: async (user) => ({ ...user, posts: await posts.titlesOf(user.id) })
+ * })
  * ```
  */
-function defineResource(transform) {
-    return new class extends Resource {
-        toArray(model, context) {
-            return transform(model, context);
+function defineResource(definition, dependencies = {}) {
+    // Assigned after construction, not through it: the class constructor is the container's, and it
+    // only reads names this module binds. An explicit object is the imperative form's business.
+    const resource = new class extends Resource {
+        constructor() {
+            super();
+            if (dependencies.checker !== undefined) {
+                this.checker = dependencies.checker;
+            }
+            if (dependencies.onViolation !== undefined) {
+                this.onViolation = dependencies.onViolation;
+            }
+        }
+        async schema(context) {
+            if (typeof definition.schema !== 'function') {
+                return definition.schema;
+            }
+            const build = definition.schema;
+            return await build(context);
         }
     }();
+    if (definition.fragments !== undefined) {
+        const declared = definition.fragments;
+        resource.fragments = async (context) => {
+            if (typeof declared !== 'function') {
+                return declared;
+            }
+            return await declared(context);
+        };
+    }
+    if (definition.data !== undefined) {
+        resource.data = definition.data;
+    }
+    return resource;
 }
 
 /**
@@ -203,59 +494,18 @@ const RETURNS_KEY = '@stone-js/resources/returns';
  */
 const API_RESOURCE_KEY = '@stone-js/resources/resource';
 
-/**
- * Build-phase middleware: collect every class registered with `@ApiResource` into the registry.
- *
- * The same scan the router does for its route definitions, applied to this module's own key. After it
- * runs, `stone.resources.registry` maps each alias to its class, so a route or a handler can name a
- * resource instead of importing it, and `@stone-js/openapi` can walk the registry to publish response
- * shapes without loading anything itself.
- *
- * @param context - The blueprint context.
- * @param next - The next blueprint middleware.
- * @returns The blueprint.
- */
-async function ApiResourceMiddleware(context, next) {
-    const registered = context
-        .modules
-        .filter((module) => hasMetadata(module, API_RESOURCE_KEY))
-        .reduce((registry, module) => {
-        const { alias } = getMetadata(module, API_RESOURCE_KEY, {});
-        return { ...registry, [alias ?? module.name]: module };
-    }, {});
-    if (Object.keys(registered).length > 0) {
-        context.blueprint.set('stone.resources.registry', {
-            ...context.blueprint.get('stone.resources.registry', {}),
-            ...registered
-        });
-    }
-    return await next(context);
-}
-/**
- * Meta blueprint middleware for resource discovery.
- */
-const MetaApiResourceMiddleware = {
-    module: ApiResourceMiddleware,
-    priority: 5
-};
-
 /**
  * Route middleware: shapes what a route returns, after its handler ran.
  *
  * A route says what it exposes, once, where the route is defined:
  *
  * ```ts
- * @Get('/users/:id', { resource: userResource })
+ * @Get('/users/:id', { resource: UserResource })
  * ```
  *
- * The handler then returns its domain model, whole, and this middleware applies the resource on the
- * way out. That is the point: a service should not have to know which fields are public, and a
- * handler should not have to remember to strip them. Whatever the model gains later, a password
- * hash, an internal flag, is not exposed by accident, because the resource decides what leaves.
- *
- * It runs on the raw value the handler returned, before any response wrapping, so it knows nothing
- * of HTTP and works in every context. Sparse fieldsets are read from the event, so `?fields=id,name`
- * narrows the output without the route changing.
+ * The handler returns its domain model, whole, and this applies the resource on the way out. That is
+ * the point: a service should not have to know which fields are public, and a handler should not have
+ * to remember to strip them.
  */
 class ResourceRouteMiddleware {
     blueprint;
@@ -270,6 +520,13 @@ class ResourceRouteMiddleware {
     /**
      * Run the handler, then shape what it returned.
      *
+     * It handles both of the things a handler may hand back, which is the part that used to be wrong. A
+     * handler carrying a response decorator (`@JsonHttpResponse(201)`) has already been turned into a
+     * response by the time any route middleware runs, because that decorator wraps the method itself.
+     * Projecting the response object produced an empty payload and dropped the status with it. So a
+     * response is now projected **through its content**, in place: the payload is shaped and the status,
+     * the headers and everything else the handler chose are left exactly as they were.
+     *
      * @param event - The incoming event.
      * @param next - The next middleware.
      * @returns The shaped output, or the untouched result when the route declares no resource.
@@ -280,8 +537,44 @@ class ResourceRouteMiddleware {
         if (resource === undefined || result === undefined || result === null) {
             return result;
         }
-        const context = contextFromEvent(event);
-        return (Array.isArray(result) ? resource.collection(result, context) : resource.item(result, context));
+        const context = contextFromEvent(event, this.blueprint, {
+            onViolation: this.blueprint.get('stone.resources', {}).onViolation
+        });
+        if (this.isContentBearing(result)) {
+            const shaped = await this.shape(resource, result.content, context);
+            result.setContent(shaped);
+            return result;
+        }
+        return await this.shape(resource, result, context);
+    }
+    /**
+     * Project a value, whether it is one model or many.
+     *
+     * @param resource - The resource to apply.
+     * @param value - The value the handler produced.
+     * @param context - The resource context.
+     * @returns The projected value.
+     */
+    async shape(resource, value, context) {
+        if (value === undefined || value === null) {
+            return value;
+        }
+        return Array.isArray(value)
+            ? await resource.collection(value, context)
+            : await resource.item(value, context);
+    }
+    /**
+     * Whether a value is a response carrying a payload this can replace.
+     *
+     * Duck-typed: the kernel is agnostic, and each platform has its own response type.
+     *
+     * @param value - The value to test.
+     * @returns Whether it carries content.
+     */
+    isContentBearing(value) {
+        return typeof value === 'object' && value !== null &&
+            typeof value.setContent === 'function' &&
+            'content' in value;
     }
     /**
      * The resource the matched route declared, with a registered name resolved to its resource.
@@ -348,7 +641,8 @@ class ResourceRouteMiddleware {
     }
     /**
      * Resolve a registered entry: a resource class goes through the container, so its constructor gets
-     * the services it asked for and `toArray` can use them, i18n included.
+     * the services it asked for — the validator it holds its own contract against, and whatever its
+     * `data()` needs to complete a model.
      *
      * @param entry - A resource, or a class to resolve into one.
      * @returns The resource.
@@ -358,7 +652,9 @@ class ResourceRouteMiddleware {
             return entry;
         }
         const ResourceClass = entry;
-        return this.container?.resolve?.(ResourceClass, true) ?? new ResourceClass({});
+        // `resolve(Class, true)` uses the binding `@ApiResource` declared, and binds it as a singleton
+        // when there is none, so a resource is built once with its dependencies wired either way.
+        return this.container?.resolve?.(ResourceClass, true) ?? new ResourceClass();
     }
 }
 /**
@@ -374,27 +670,39 @@ const MetaResourceRouteMiddleware = {
 };
 
 /**
- * Class decorator: register a resource class under a name.
- *
- * ```ts
- * @ApiResource('user')
- * export class UserResource extends Resource<User> {
- *   toArray (user: User) { return { id: user.id, name: user.name } }
- * }
- * ```
+ * Build-phase middleware: collect every class registered with `@ApiResource` into the registry.
  *
- * Routes and handlers then refer to it by name (`@Returns('user')`, or `{ resource: 'user' }`), so
- * resources live in their own files, organised however the application likes, and nothing has to be
- * imported at the route. The class is resolved by the container, so its constructor receives services
- * and `toArray` can use them: a resource that formats dates for the caller's locale needs i18n, and
- * this is how it gets it.
+ * The same scan the router does for its route definitions, applied to this module's own key. After it
+ * runs, `stone.resources.registry` maps each alias to its class, so a route or a handler can name a
+ * resource instead of importing it, and `@stone-js/openapi` can walk the registry to publish response
+ * shapes without loading anything itself.
  *
- * @param alias - The name the resource is registered under. Defaults to the class name, which the
- * discovery middleware fills in, since it is the one holding the class.
- * @returns A class decorator.
+ * @param context - The blueprint context.
+ * @param next - The next blueprint middleware.
+ * @returns The blueprint.
  */
-const ApiResource = (alias) => {
-    return setClassMetadata(API_RESOURCE_KEY, { alias });
+async function ApiResourceMiddleware(context, next) {
+    const registered = context
+        .modules
+        .filter((module) => hasMetadata(module, API_RESOURCE_KEY))
+        .reduce((registry, module) => {
+        const { alias } = getMetadata(module, API_RESOURCE_KEY, {});
+        return { ...registry, [alias ?? module.name]: module };
+    }, {});
+    if (Object.keys(registered).length > 0) {
+        context.blueprint.set('stone.resources.registry', {
+            ...context.blueprint.get('stone.resources.registry', {}),
+            ...registered
+        });
+    }
+    return await next(context);
+}
+/**
+ * Meta blueprint middleware for resource discovery.
+ */
+const MetaApiResourceMiddleware = {
+    module: ApiResourceMiddleware,
+    priority: 5
 };
 
 /**
@@ -411,9 +719,24 @@ const ApiResource = (alias) => {
  * export const Application = defineStoneApp({ name: 'my-app' }, [resourcesBlueprint])
  * ```
  */
+/**
+ * The reader every resource holds its contract against, as a service.
+ *
+ * Bound so a resource's constructor can simply ask for it. A dependency read off the container that
+ * nothing ever bound is not optional, it is a crash, which is what made every container-resolved
+ * resource fail on a service nobody was told to register. The fix is the registration, not a
+ * conditional read.
+ */
+const MetaContractChecker = {
+    module: ContractChecker,
+    isClass: true,
+    singleton: true,
+    alias: 'contractChecker'
+};
 const resourcesBlueprint = {
     stone: {
         resources: {},
+        services: [MetaContractChecker],
         blueprint: {
             middleware: [
                 MetaApiResourceMiddleware
@@ -427,6 +750,49 @@ const resourcesBlueprint = {
     }
 };
 
+/**
+ * Declare a class as an API resource.
+ *
+ * Three statements in one, which is why nothing has to be wired by hand:
+ *
+ * 1. **It is a service.** The container builds it, as a singleton, which means its constructor is
+ *    auto-wired like any other class: whatever it destructures is resolved for it, from the checker
+ *    it holds its contract against to the repository its `data()` needs to complete a model. Nothing
+ *    reads dependencies conditionally, because the container has them.
+ * 2. **It is reachable by name.** The alias is bound in the container as `resource:<name>`, prefixed
+ *    on purpose: an application is free to bind its own `user` service, and a resource named `user`
+ *    must not compete for that name.
+ * 3. **It activates the module.** The blueprint comes with the decorator, so a resource declared this
+ *    way is registered and projected without a second gesture, and `resource: 'user'` on a route
+ *    resolves to this class.
+ *
+ * @param alias - The name a route refers to it by. Defaults to the class name.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```ts
+ * @ApiResource('user')
+ * export class UserResource extends Resource<User> {
+ *   constructor (private readonly posts: PostRepository) { super() }
+ *   schema (): unknown { return z.object({ id: z.number(), name: z.string() }) }
+ * }
+ * ```
+ */
+const ApiResource = (alias) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        const name = alias ?? target.name;
+        setMetadata(context, API_RESOURCE_KEY, { alias: name });
+        setMetadata(context, SERVICE_KEY, { singleton: true, isClass: true, alias: `resource:${name}` });
+        addBlueprint(target, context, resourcesBlueprint, {
+            stone: {
+                resources: {
+                    registry: { [name]: target }
+                }
+            }
+        });
+    });
+};
+
 /**
  * Class decorator: shape what routes return, declaratively.
  *
@@ -483,4 +849,4 @@ const Returns = (resource) => {
     });
 };
 
-export { API_RESOURCE_KEY, ApiResource, ApiResourceMiddleware, MetaApiResourceMiddleware, MetaResourceRouteMiddleware, RETURNS_KEY, Resource, ResourceRouteMiddleware, Resources, Returns, applyFields, contextFromEvent, defineResource, except, only, resourcesBlueprint, stripUndefined };
+export { API_RESOURCE_KEY, ApiResource, ApiResourceMiddleware, ContractChecker, MetaApiResourceMiddleware, MetaContractChecker, MetaResourceRouteMiddleware, RETURNS_KEY, Resource, ResourceContractError, ResourceRouteMiddleware, Resources, Returns, applyFields, contextFromEvent, defineResource, except, only, resourcesBlueprint, stripUndefined };