@stone-js/resources 0.8.8 → 0.8.10

package/dist/middleware/BlueprintMiddleware.d.ts

@@ -0,0 +1,18 @@
+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>;

package/dist/middleware/ResourceRouteMiddleware.d.ts

@@ -0,0 +1,106 @@
+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, a class to resolve, or the
+ * name of one registered under `stone.resources.registry`.
+ */
+export type RouteResource = IResource<any, any> | string;
+/**
+ * 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.
+ */
+export declare class ResourceRouteMiddleware {
+    private readonly blueprint;
+    private readonly container?;
+    /**
+     * @param dependencies - Auto-wired container services.
+     */
+    constructor({ blueprint, container }: {
+        blueprint: IBlueprint;
+        container?: IContainer;
+    });
+    /**
+     * 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.
+     *
+     * @param event - The incoming event.
+     * @returns The resource, or `undefined` when the route declares none.
+     */
+    private resourceFor;
+    /**
+     * 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`.
+     */
+    private declarationFor;
+    /**
+     * What a handler declared with `@Returns`, if anything.
+     *
+     * @param handler - The handler about to run.
+     * @returns What the matching method declared, or `undefined`.
+     */
+    private declaredOnHandler;
+    /**
+     * 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.
+     */
+    private resolve;
+}
+/**
+ * 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.
+ */
+export declare const MetaResourceRouteMiddleware: MetaMiddleware<any, any>;

package/dist/options/ResourcesBlueprint.d.ts

@@ -0,0 +1,65 @@
+import { IResource } from '../declarations.js';
+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.
+     *
+     * ```ts
+     * blueprint.set('stone.resources.registry', { user: userResource })
+     * // then, on the route: { resource: 'user' }
+     * ```
+     *
+     * Naming a resource that is not registered fails loudly at request time rather than returning the
+     * model unshaped, because an unshaped model is exactly what a resource exists to prevent.
+     */
+    registry?: Record<string, IResource<any, any>>;
+}
+/**
+ * Application config augmented with the resources bucket.
+ */
+export interface ResourcesAppConfig extends Partial<AppConfig> {
+    resources: ResourcesConfig;
+}
+/**
+ * Blueprint for the resources module.
+ */
+export interface ResourcesBlueprint extends StoneBlueprint {
+    stone: ResourcesAppConfig;
+}
+/**
+ * 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])
+ * ```
+ */
+export declare const resourcesBlueprint: ResourcesBlueprint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/resources",
-  "version": "0.8.8",
+  "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": [
@@ -68,6 +69,12 @@
       "beforeEach"
     ]
   },
+  "dependencies": {
+    "@stone-js/config": "0.8.10"
+  },
+  "peerDependencies": {
+    "@stone-js/core": "0.8.10"
+  },
   "scripts": {
     "lint": "ts-standard src",
     "lint:fix": "ts-standard --fix src tests",