@stone-js/resources 0.8.11 → 0.8.12

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;
 }

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.12",
   "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.12"
   },
   "ts-standard": {
     "globals": [
@@ -71,10 +71,10 @@
     ]
   },
   "dependencies": {
-    "@stone-js/config": "0.8.11"
+    "@stone-js/config": "0.8.12"
   },
   "peerDependencies": {
-    "@stone-js/core": "0.8.11"
+    "@stone-js/core": "0.8.12"
   },
   "scripts": {
     "lint": "ts-standard src",

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>;