@stone-js/resources 0.8.8 → 0.8.10

package/dist/index.js

@@ -1,3 +1,147 @@
+import { RuntimeError, setClassMetadata, hasMetadata, getMetadata, classDecoratorLegacyWrapper, 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).
  *
@@ -60,88 +204,230 @@ 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.
+ *
+ * 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 ?? [];
+    }
+}
+
+/**
+ * Base API resource — the layer responsible for exposing data.
+ *
+ * A resource answers two questions, and the second is what makes it worth having. *What leaves?* —
+ * and *what did you promise leaves?* The promise is a schema, so the same declaration validates the
+ * response, documents it in the published contract, and lets a caller ask for a named subset of it.
+ *
+ * Projection is the schema's own work: what the schema does not describe is not exposed, so a field
+ * added to a model later — a password hash, an internal flag — cannot leak by being forgotten.
  *
  * @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))
- *     }
+ * @ApiResource('user')
+ * export class UserResource extends Resource<User> {
+ *   constructor ({ posts }: { posts: PostService }) {
+ *     super()
+ *     this.posts = posts
+ *   }
+ *
+ *   schema () {
+ *     return z.object({ id: z.number(), name: z.string(), posts: z.array(z.string()).optional() })
+ *   }
+ *
+ *   fragments () {
+ *     return { summary: z.object({ id: z.number(), name: z.string() }) }
+ *   }
+ *
+ *   async data (user: User) {
+ *     return { ...user, posts: await this.posts.titlesOf(user.id) }
  *   }
  * }
  * ```
  */
 class Resource {
+    checker;
+    onViolation;
+    /**
+     * @param dependencies - Auto-wired services. Nothing is required: this module reads schemas with its
+     *                       own checker, so exposing data never depends on a validation module being
+     *                       enabled. Pass `checker` to substitute a dialect of your own.
+     */
+    constructor(dependencies = {}) {
+        this.checker = dependencies.checker ?? ContractChecker.create();
+        this.onViolation = dependencies.onViolation ?? 'throw';
+    }
     /**
-     * Transform one model, applying the requested sparse fieldset and dropping undefined fields.
+     * 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).
@@ -154,7 +440,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.
@@ -167,25 +453,378 @@ 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(definition, dependencies = {}) {
+    const resource = new class extends Resource {
+        async schema(context) {
+            if (typeof definition.schema !== 'function') {
+                return definition.schema;
+            }
+            const build = definition.schema;
+            return await build(context);
+        }
+    }(dependencies);
+    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;
+}
+
+/**
+ * Metadata key carrying what a handler method declared with `@Returns`.
+ *
+ * The module owns its key, which is what makes it independent: a resource shapes the output whether
+ * or not a router is in play, because the declaration lives on the handler, not on a route.
+ */
+const RETURNS_KEY = '@stone-js/resources/returns';
+/**
+ * Metadata key carrying the alias a resource class registered itself under.
+ */
+const API_RESOURCE_KEY = '@stone-js/resources/resource';
+
+/**
+ * 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 } }
+ * }
  * ```
+ *
+ * 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.
+ *
+ * @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.
  */
-function defineResource(transform) {
-    return new class extends Resource {
-        toArray(model, context) {
-            return transform(model, context);
+const ApiResource = (alias) => {
+    return setClassMetadata(API_RESOURCE_KEY, { alias });
+};
+
+/**
+ * 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 })
+ * ```
+ *
+ * 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;
+    container;
+    /**
+     * @param dependencies - Auto-wired container services.
+     */
+    constructor({ blueprint, container }) {
+        this.blueprint = blueprint;
+        this.container = container;
+    }
+    /**
+     * 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.
+     */
+    async handle(event, next) {
+        const resource = this.resourceFor(event);
+        const result = await next(event);
+        if (resource === undefined || result === undefined || result === null) {
+            return result;
+        }
+        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.
+     *
+     * @param event - The incoming event.
+     * @returns The resource, or `undefined` when the route declares none.
+     */
+    resourceFor(event) {
+        const declared = this.declarationFor(event);
+        if (declared === undefined) {
+            return undefined;
+        }
+        if (typeof declared !== 'string') {
+            return this.resolve(declared);
+        }
+        const registry = this.blueprint.get('stone.resources', {}).registry ?? {};
+        const resource = registry[declared];
+        if (resource === undefined) {
+            throw new TypeError(`The route declares \`resource: '${declared}'\`, but no resource is registered under that ` +
+                'name. Register it with `blueprint.set(\'stone.resources.registry\', { ' + declared + ': … })`, ' +
+                'or declare the resource inline on the route.');
+        }
+        return this.resolve(resource);
+    }
+    /**
+     * What the handler about to run declared, from either of the two places it may live.
+     *
+     * The route's own option comes first, because when a router is in play a route is the single
+     * description of itself. Failing that, the handler's own `@Returns` metadata is read: that form owns
+     * its key and needs no router, so the same module shapes the output of a routed request, a
+     * single-handler service, a CLI command or a browser event.
+     *
+     * @param event - The incoming event.
+     * @returns What was declared, or `undefined`.
+     */
+    declarationFor(event) {
+        // Duck-typed throughout: the kernel is agnostic, and an event without a router carries no route.
+        const route = event.getRoute?.();
+        const onRoute = route?.getOption?.('resource');
+        if (onRoute !== undefined) {
+            return onRoute;
+        }
+        const handler = route?.getOption?.('handler') ??
+            this.blueprint.get('stone.kernel.eventHandler', {});
+        return this.declaredOnHandler(handler);
+    }
+    /**
+     * What a handler declared with `@Returns`, if anything.
+     *
+     * @param handler - The handler about to run.
+     * @returns What the matching method declared, or `undefined`.
+     */
+    declaredOnHandler(handler) {
+        const module = handler?.module;
+        if (module === undefined || !hasMetadata(module, RETURNS_KEY)) {
+            return undefined;
         }
-    }();
+        const declarations = getMetadata(module, RETURNS_KEY, []);
+        const action = handler?.action;
+        // A single-handler module declares one; a controller declares one per method.
+        return (action === undefined
+            ? declarations[0]
+            : declarations.find((declaration) => declaration.action === action))?.resource;
+    }
+    /**
+     * Resolve a registered entry: a resource class goes through the container, so its constructor gets
+     * 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.
+     */
+    resolve(entry) {
+        if (typeof entry !== 'function') {
+            return entry;
+        }
+        const ResourceClass = entry;
+        return this.container?.resolve?.(ResourceClass, true) ?? new ResourceClass({});
+    }
 }
+/**
+ * Meta middleware for route-declared resources.
+ *
+ * Registered on `stone.router.middleware` by `resourcesBlueprint`. Its priority puts it outside
+ * validation, so a request is shaped on the way out after having been validated on the way in.
+ */
+const MetaResourceRouteMiddleware = {
+    module: ResourceRouteMiddleware,
+    isClass: true,
+    priority: 4
+};
+
+/**
+ * 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
+};
+
+/**
+ * Opt-in blueprint: register it to shape what routes return.
+ *
+ * It contributes the route middleware that applies whatever a route declared under `resource`.
+ * `stone.router.middleware` is an array, so this merges with the rest of the app. The middleware is
+ * a no-op on routes that declare nothing.
+ *
+ * @example
+ * ```typescript
+ * import { resourcesBlueprint } from '@stone-js/resources'
+ *
+ * export const Application = defineStoneApp({ name: 'my-app' }, [resourcesBlueprint])
+ * ```
+ */
+const resourcesBlueprint = {
+    stone: {
+        resources: {},
+        blueprint: {
+            middleware: [
+                MetaApiResourceMiddleware
+            ]
+        },
+        router: {
+            middleware: [
+                MetaResourceRouteMiddleware
+            ]
+        }
+    }
+};
+
+/**
+ * Class decorator: shape what routes return, declaratively.
+ *
+ * `@Resources()` installs the route middleware that applies whatever a route declared under
+ * `resource`, so a handler returns its domain model and only what the resource allows leaves the
+ * application.
+ *
+ * @param options - The resources configuration. Everything is optional.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * import { Resources } from '@stone-js/resources'
+ *
+ * @Resources({ registry: { user: userResource } })
+ * @StoneApp({ name: 'my-app' })
+ * export class Application {}
+ * ```
+ */
+const Resources = (options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        // The blueprint is the single source of truth for what the module declares; the decorator only
+        // overrides what it can, its options bucket.
+        const blueprint = cloneValue(resourcesBlueprint);
+        blueprint.stone.resources = { ...blueprint.stone.resources, ...options };
+        addBlueprint(target, context, blueprint);
+    });
+};
+
+/**
+ * Method decorator: declare what a handler exposes.
+ *
+ * ```ts
+ * @Returns(userResource)   // the resource itself
+ * @Returns('user')         // a registered resource class
+ * ```
+ *
+ * The counterpart of `@Validate`: one says what comes in, the other what goes out, and between them
+ * the handler is free to return its domain model whole. Whatever the model gains later, a password
+ * hash, an internal flag, does not leak, because the resource decides what leaves.
+ *
+ * Like `@Validate`, this knows nothing about the router. The declaration is recorded on the handler
+ * under this module's own key, so it works in a routed application, a single-handler service, a CLI
+ * command or the browser. When a router is in play you may put it on the route instead
+ * (`@Get('/users/:id', { resource: userResource })`), which keeps everything a route does in one
+ * place; both forms end up in the same middleware.
+ *
+ * @param resource - What the handler exposes.
+ * @returns A method decorator.
+ */
+const Returns = (resource) => {
+    return methodDecoratorLegacyWrapper((_target, context) => {
+        addMetadata(context, RETURNS_KEY, { action: context.name, resource });
+    });
+};
 
-export { Resource, applyFields, contextFromEvent, defineResource, except, only, stripUndefined };
+export { API_RESOURCE_KEY, ApiResource, ApiResourceMiddleware, ContractChecker, MetaApiResourceMiddleware, MetaResourceRouteMiddleware, RETURNS_KEY, Resource, ResourceContractError, ResourceRouteMiddleware, Resources, Returns, applyFields, contextFromEvent, defineResource, except, only, resourcesBlueprint, stripUndefined };