@stone-js/resources 0.8.11 → 0.8.13

package/dist/Resource.d.ts

@@ -45,7 +45,7 @@ export interface ResourceDependencies {
     /** The reader every projection is held against, bound as `contractChecker`. */
     contractChecker?: IContractChecker;
 }
-export declare abstract class Resource<Model = unknown, Output extends ResourceOutput = ResourceOutput> implements IResource<Model, Output> {
+export declare abstract class Resource<Model = unknown, Output extends ResourceOutput = ResourceOutput, EventType = unknown, PrincipalType = unknown> implements IResource<Model, Output, EventType, PrincipalType> {
     protected checker: IContractChecker;
     protected onViolation: ContractViolationPolicy;
     /**
@@ -68,7 +68,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @param context - The resource context.
      * @returns The schema.
      */
-    abstract schema(context: ResourceContext): ResourceSchema | Promise<ResourceSchema>;
+    abstract schema(context: ResourceContext<EventType, PrincipalType>): ResourceSchema | Promise<ResourceSchema>;
     /**
      * Project one model.
      *
@@ -81,7 +81,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @returns The projected output.
      * @throws {ResourceContractError} When the data breaks the contract and the policy is `throw`.
      */
-    item(model: Model, context?: ResourceContext): Promise<Output>;
+    item(model: Model, context?: ResourceContext<EventType, PrincipalType>): Promise<Output>;
     /**
      * Project a collection.
      *
@@ -93,7 +93,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @param context - The resource context.
      * @returns The projected collection.
      */
-    collection(models: Model[], context?: ResourceContext): Promise<Output[]>;
+    collection(models: Model[], context?: ResourceContext<EventType, PrincipalType>): Promise<Output[]>;
     /**
      * Project into a `{ data, meta }` envelope.
      *
@@ -102,19 +102,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @param meta - Optional metadata (pagination, counts, …).
      * @returns The envelope.
      */
-    response(models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>): Promise<ResourceEnvelope<Output | Output[]>>;
-    /**
-     * Optional: shape or complete the model before it meets the schema.
-     *
-     * `declare`, not a field: an uninitialised class field is *defined* as `undefined` on the instance,
-     * which would shadow the very method a subclass wrote — the override would exist on the prototype
-     * and never be reached. This states the type and emits nothing.
-     */
-    data?: (model: Model, context: ResourceContext) => Promiseable<unknown>;
-    /**
-     * Named subsets a caller may ask for. Override to expose fragments.
-     */
-    fragments?: (context: ResourceContext) => Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>;
+    response(models: Model | Model[], context?: ResourceContext<EventType, PrincipalType>, meta?: Record<string, unknown>): Promise<ResourceEnvelope<Output | Output[]>>;
     /**
      * The schema to hold this projection against: the requested fragment when the resource exposes one,
      * the full contract otherwise.
@@ -126,7 +114,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @param context - The resource context.
      * @returns The schema.
      */
-    protected schemaFor(context: ResourceContext): Promise<ResourceSchema>;
+    protected schemaFor(context: ResourceContext<EventType, PrincipalType>): Promise<ResourceSchema>;
     /**
      * Hold the data against the contract, and return what the contract describes.
      *
@@ -158,3 +146,28 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      */
     protected whenIncluded<T>(context: ResourceContext, name: string, value: T | (() => T)): T | undefined;
 }
+/**
+ * The two optional hooks, declared as methods rather than as properties.
+ *
+ * A property-typed function is contravariant on its parameters, and TypeScript refuses a method where
+ * the base declared a property. Between them, those two rules meant a subclass could neither narrow the
+ * context nor write `async data (model, context) {}`, which is the form every example uses. Declared
+ * here, on an interface merged with the class, both forms are accepted and the type parameters actually
+ * reach the signature a subclass writes.
+ */
+export interface Resource<Model, Output extends ResourceOutput, EventType, PrincipalType> {
+    /**
+     * Optional: shape or complete the model before it meets the schema.
+     *
+     * A method signature, deliberately, against the repository's own lint rule: a property-typed
+     * function is contravariant on its parameters, so a subclass narrowing the context was rejected, and
+     * TypeScript separately refuses a method where the base declared a property, so
+     * `async data (model, context) {}` was rejected too. The rule's soundness argument is theoretical for
+     * an extension point; the cost was measured, in an application that could not type its resources.
+     */
+    data?(model: Model, context: ResourceContext<EventType, PrincipalType>): Promiseable<unknown>;
+    /**
+     * Named subsets a caller may ask for. Override to expose fragments.
+     */
+    fragments?(context: ResourceContext<EventType, PrincipalType>): Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>;
+}

package/dist/declarations.d.ts

@@ -15,17 +15,28 @@ export type ResourceSchema = unknown;
  * carried. The authenticated principal is part of it, because deciding what a caller may see is the
  * most common reason a projection differs between two callers.
  */
-export interface ResourceContext {
-    /** Requested sparse fieldset — narrows the output to these top-level keys. */
+export interface ResourceContext<EventType = unknown, PrincipalType = unknown> {
+    /** Requested sparse fieldset: narrows the output to these top-level keys. */
     fields?: string[];
     /** Requested relations to embed. */
     include?: string[];
     /** The requested fragment, when the caller asked for one by name. */
     fragment?: string;
-    /** The authenticated principal, when the application has one. */
-    principal?: unknown;
-    /** The event being answered, for a resource that needs more than the parameters above. */
-    event?: unknown;
+    /**
+     * The authenticated principal, when the application has one.
+     *
+     * Typed by the resource, because deciding what a caller may see is the most common reason two
+     * callers get different shapes, and `unknown` makes every such decision a cast. The default stays
+     * `unknown`: this module never assumes an application has users, let alone what a user is.
+     */
+    principal?: PrincipalType;
+    /**
+     * The event being answered, for a resource that needs more than the parameters above.
+     *
+     * Typed by the resource for the same reason, and `unknown` by default because the module is
+     * agnostic of the platform the event came from.
+     */
+    event?: EventType;
     /** Anything else a resource needs. */
     [key: string]: unknown;
 }
@@ -47,29 +58,29 @@ export interface ResourceEnvelope<T> {
  * and to the resource itself, which validates against it before anything leaves. One declaration, three
  * consumers, and no way for the documentation to drift from the response.
  */
-export interface IResource<Model = unknown, Output = ResourceOutput> {
+export interface IResource<Model = unknown, Output = ResourceOutput, EventType = unknown, PrincipalType = unknown> {
     /** The contract: the schema every projection is validated against and documented from. */
-    schema: (context: ResourceContext) => ResourceSchema | Promise<ResourceSchema>;
+    schema(context: ResourceContext<EventType, PrincipalType>): ResourceSchema | Promise<ResourceSchema>;
     /**
      * Named subsets a caller may ask for, each with its own schema.
      *
      * A fragment is not a filter: it is a contract of its own, documented and validated like the full
      * one. That is what makes `?view=summary` safe to expose.
      */
-    fragments?: (context: ResourceContext) => Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>;
+    fragments?(context: ResourceContext<EventType, PrincipalType>): Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>;
     /**
      * Optional hook to shape or complete the model before it meets the schema.
      *
      * Asynchronous, and resolved from the container, so it may reach any service: fetch a relation,
      * translate a label, compute a total. Whatever it returns is what the schema then validates.
      */
-    data?: (model: Model, context: ResourceContext) => Promiseable<unknown>;
+    data?(model: Model, context: ResourceContext<EventType, PrincipalType>): Promiseable<unknown>;
     /** Project one model. */
-    item: (model: Model, context?: ResourceContext) => Promise<Output>;
+    item(model: Model, context?: ResourceContext<EventType, PrincipalType>): Promise<Output>;
     /** Project a collection. */
-    collection: (models: Model[], context?: ResourceContext) => Promise<Output[]>;
+    collection(models: Model[], context?: ResourceContext<EventType, PrincipalType>): Promise<Output[]>;
     /** Project into a `{ data, meta }` envelope. */
-    response: (models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>) => Promise<ResourceEnvelope<Output | Output[]>>;
+    response(models: Model | Model[], context?: ResourceContext<EventType, PrincipalType>, meta?: Record<string, unknown>): Promise<ResourceEnvelope<Output | Output[]>>;
 }
 /** What to do when the data does not match the contract the resource published. */
 export type ContractViolationPolicy = 'throw' | 'warn';

package/dist/index.d.ts

@@ -7,7 +7,6 @@ export * from './decorators/Returns.js';
 export * from './defineResource.js';
 export * from './errors/ResourceContractError.js';
 export * from './helpers.js';
-export * from './middleware/BlueprintMiddleware.js';
 export * from './middleware/ResourceRouteMiddleware.js';
 export * from './options/ResourcesBlueprint.js';
 export * from './Resource.js';

package/dist/index.js

@@ -541,11 +541,48 @@ class ResourceRouteMiddleware {
             onViolation: this.blueprint.get('stone.resources', {}).onViolation
         });
         if (this.isContentBearing(result)) {
-            const shaped = await this.shape(resource, result.content, context);
+            const shaped = await this.shapePayload(resource, result.content, context);
             result.setContent(shaped);
             return result;
         }
-        return await this.shape(resource, result, context);
+        return await this.shapePayload(resource, result, context);
+    }
+    /**
+     * Shape a value, or shape what is inside the envelope the application declared.
+     *
+     * A page is `{ items: [...], meta: { total } }`, and `items` and `meta` are not fields of a model:
+     * projecting that object would publish the envelope as if it were the thing. An application names its
+     * own wrapper once, in `stone.resources.envelope`, and everything around the payload is left as it
+     * was, counts and cursors included.
+     *
+     * Nothing is assumed when nothing is declared, because guessing which key holds the payload would
+     * quietly mangle a model that happens to have one by that name.
+     *
+     * @param resource - The resource to apply.
+     * @param value - The value the handler produced.
+     * @param context - The resource context.
+     * @returns The projected value, wrapper intact.
+     */
+    async shapePayload(resource, value, context) {
+        const key = this.envelopeKeyOf(value);
+        if (key === undefined) {
+            return await this.shape(resource, value, context);
+        }
+        const envelope = value;
+        return { ...envelope, [key]: await this.shape(resource, envelope[key], context) };
+    }
+    /**
+     * Which declared envelope key this value carries, if any.
+     *
+     * @param value - The value the handler produced.
+     * @returns The key holding the payload, or nothing when this is not an envelope.
+     */
+    envelopeKeyOf(value) {
+        const declared = this.blueprint.get('stone.resources', {}).envelope;
+        if (declared === undefined || typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return undefined;
+        }
+        return [declared.payload].flat().find((candidate) => candidate in value);
     }
     /**
      * Project a value, whether it is one model or many.
@@ -669,42 +706,6 @@ const MetaResourceRouteMiddleware = {
     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.
  *
@@ -737,11 +738,6 @@ const resourcesBlueprint = {
     stone: {
         resources: {},
         services: [MetaContractChecker],
-        blueprint: {
-            middleware: [
-                MetaApiResourceMiddleware
-            ]
-        },
         router: {
             middleware: [
                 MetaResourceRouteMiddleware
@@ -849,4 +845,4 @@ const Returns = (resource) => {
     });
 };
 
-export { API_RESOURCE_KEY, ApiResource, ApiResourceMiddleware, ContractChecker, MetaApiResourceMiddleware, MetaContractChecker, MetaResourceRouteMiddleware, RETURNS_KEY, Resource, ResourceContractError, ResourceRouteMiddleware, Resources, Returns, applyFields, contextFromEvent, defineResource, except, only, resourcesBlueprint, stripUndefined };
+export { API_RESOURCE_KEY, ApiResource, ContractChecker, MetaContractChecker, MetaResourceRouteMiddleware, RETURNS_KEY, Resource, ResourceContractError, ResourceRouteMiddleware, Resources, Returns, applyFields, contextFromEvent, defineResource, except, only, resourcesBlueprint, stripUndefined };

package/dist/middleware/ResourceRouteMiddleware.d.ts

@@ -43,6 +43,30 @@ export declare class ResourceRouteMiddleware {
      * @returns The shaped output, or the untouched result when the route declares no resource.
      */
     handle(event: IncomingEvent, next: NextMiddleware<IncomingEvent, OutgoingResponse>): Promise<OutgoingResponse>;
+    /**
+     * Shape a value, or shape what is inside the envelope the application declared.
+     *
+     * A page is `{ items: [...], meta: { total } }`, and `items` and `meta` are not fields of a model:
+     * projecting that object would publish the envelope as if it were the thing. An application names its
+     * own wrapper once, in `stone.resources.envelope`, and everything around the payload is left as it
+     * was, counts and cursors included.
+     *
+     * Nothing is assumed when nothing is declared, because guessing which key holds the payload would
+     * quietly mangle a model that happens to have one by that name.
+     *
+     * @param resource - The resource to apply.
+     * @param value - The value the handler produced.
+     * @param context - The resource context.
+     * @returns The projected value, wrapper intact.
+     */
+    private shapePayload;
+    /**
+     * Which declared envelope key this value carries, if any.
+     *
+     * @param value - The value the handler produced.
+     * @returns The key holding the payload, or nothing when this is not an envelope.
+     */
+    private envelopeKeyOf;
     /**
      * Project a value, whether it is one model or many.
      *

package/dist/options/ResourcesBlueprint.d.ts

@@ -3,6 +3,13 @@ import { AppConfig, MetaService, StoneBlueprint } from '@stone-js/core';
 /**
  * Resources configuration bucket (`stone.resources`).
  */
+/**
+ * The envelope an application wraps its payloads in.
+ */
+export interface ResourceEnvelopeConfig {
+    /** The key, or keys, that hold the payload to shape. */
+    payload: string | string[];
+}
 export interface ResourcesConfig {
     /**
      * The query parameters a caller uses to ask for a shape.
@@ -35,6 +42,22 @@ export interface ResourcesConfig {
      * model unshaped, because an unshaped model is exactly what a resource exists to prevent.
      */
     registry?: Record<string, IResource<any, any>>;
+    /**
+     * The envelope this application wraps its payloads in, if it wraps them at all.
+     *
+     * A handler answering a page returns something like `{ items: [...], meta: { total } }`, and `items`
+     * and `meta` are not fields of a model: shaping that object would publish the wrapper as if it were
+     * the thing. Naming the word once is enough, and everything around the payload is left as it was,
+     * counts and cursors included.
+     *
+     * ```ts
+     * blueprint.set('stone.resources.envelope', { payload: 'items' })
+     * ```
+     *
+     * Undeclared by default, because guessing which key holds the payload would quietly mangle a model
+     * that happens to have one by that name.
+     */
+    envelope?: ResourceEnvelopeConfig;
 }
 /**
  * Application config augmented with the resources bucket.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/resources",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "description": "Framework-agnostic API resources for Stone.js. Shape what your domain exposes — sparse fieldsets, conditional fields, includes and envelopes — decoupled from controllers, the same on backend and frontend.",
   "author": "Mr. Stone <evensstone@gmail.com>",
   "license": "MIT",
@@ -58,7 +58,7 @@
     "typescript": "^5.6.3",
     "vitest": "^3.2.4",
     "zod": "^3.25.76",
-    "@stone-js/service-container": "0.8.11"
+    "@stone-js/service-container": "0.8.13"
   },
   "ts-standard": {
     "globals": [
@@ -71,10 +71,10 @@
     ]
   },
   "dependencies": {
-    "@stone-js/config": "0.8.11"
+    "@stone-js/config": "0.8.13"
   },
   "peerDependencies": {
-    "@stone-js/core": "0.8.11"
+    "@stone-js/core": "0.8.13"
   },
   "scripts": {
     "lint": "ts-standard src",
@@ -83,10 +83,11 @@
     "doc": "typedoc",
     "clean": "rimraf dist",
     "build": "rollup -c",
-    "test": "vitest run",
+    "test": "vitest run && npm run test:types",
     "test:cvg": "npm run test -- --coverage",
     "test:text": "npm run test:cvg -- --coverage.reporter=text",
     "test:html": "npm run test:cvg -- --coverage.reporter=html",
-    "test:clover": "npm run test:cvg -- --coverage.reporter=clover"
+    "test:clover": "npm run test:cvg -- --coverage.reporter=clover",
+    "test:types": "tsc -p tsconfig.types.json"
   }
 }

package/dist/middleware/BlueprintMiddleware.d.ts

@@ -1,18 +0,0 @@
-import { BlueprintContext, ClassType, IBlueprint, NextMiddleware, type MetaMiddleware } from '@stone-js/core';
-/**
- * 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.
- */
-export declare function ApiResourceMiddleware(context: BlueprintContext<IBlueprint, ClassType>, next: NextMiddleware<BlueprintContext<IBlueprint, ClassType>, IBlueprint>): Promise<IBlueprint>;
-/**
- * Meta blueprint middleware for resource discovery.
- */
-export declare const MetaApiResourceMiddleware: MetaMiddleware<any, any>;