@stone-js/resources 0.8.9 → 0.8.10

package/dist/middleware/ResourceRouteMiddleware.d.ts

@@ -1,8 +1,8 @@
 import { IResource } from '../declarations.js';
 import { IBlueprint, IContainer, IncomingEvent, NextMiddleware, OutgoingResponse, type MetaMiddleware } from '@stone-js/core';
 /**
- * The shape a route's `resource` option may take: the resource itself, or the name of one
- * registered under `stone.resources.registry`.
+ * The shape a route's `resource` option may take: the resource itself, a class to resolve, or the
+ * name of one registered under `stone.resources.registry`.
  */
 export type RouteResource = IResource<any, any> | string;
 /**
@@ -11,17 +11,12 @@ export type RouteResource = IResource<any, any> | string;
  * 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.
  */
 export declare class ResourceRouteMiddleware {
     private readonly blueprint;
@@ -36,11 +31,36 @@ export declare 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.
      */
     handle(event: IncomingEvent, next: NextMiddleware<IncomingEvent, OutgoingResponse>): Promise<OutgoingResponse>;
+    /**
+     * 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.
+     */
+    private shape;
+    /**
+     * 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.
+     */
+    private isContentBearing;
     /**
      * The resource the matched route declared, with a registered name resolved to its resource.
      *
@@ -69,7 +89,8 @@ export declare class ResourceRouteMiddleware {
     private declaredOnHandler;
     /**
      * 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.

package/dist/options/ResourcesBlueprint.d.ts

@@ -4,6 +4,25 @@ import { AppConfig, StoneBlueprint } from '@stone-js/core';
  * Resources configuration bucket (`stone.resources`).
  */
 export interface ResourcesConfig {
+    /**
+     * The query parameters a caller uses to ask for a shape.
+     *
+     * Configuration rather than convention: an API that already answers `?only=` keeps its vocabulary
+     * instead of gaining a second one. Defaults: `fields`, `include`, `view`.
+     */
+    params?: {
+        fields?: string;
+        include?: string;
+        fragment?: string;
+    };
+    /**
+     * What to do when a projection breaks the contract its resource publishes.
+     *
+     * `throw` (the default) refuses to answer, because a caller cannot detect a broken contract and a
+     * consumer generated from it breaks on the field that is missing. `warn` chooses availability over
+     * integrity, explicitly, and puts the breach in the log.
+     */
+    onViolation?: 'throw' | 'warn';
     /**
      * Named resources a route can refer to by name, instead of importing them at the route.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/resources",
-  "version": "0.8.9",
+  "version": "0.8.10",
   "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",
@@ -56,7 +56,8 @@
     "typedoc": "^0.28.6",
     "typedoc-plugin-markdown": "^4.7.0",
     "typescript": "^5.6.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^3.25.76"
   },
   "ts-standard": {
     "globals": [
@@ -69,10 +70,10 @@
     ]
   },
   "dependencies": {
-    "@stone-js/config": "0.8.9"
+    "@stone-js/config": "0.8.10"
   },
   "peerDependencies": {
-    "@stone-js/core": "0.8.9"
+    "@stone-js/core": "0.8.10"
   },
   "scripts": {
     "lint": "ts-standard src",