@stone-js/resources 0.8.7 → 0.8.9

package/dist/Resource.d.ts

@@ -1,4 +1,4 @@
-import { IResource, ResourceContext, ResourceEnvelope, ResourceOutput } from './declarations';
+import { IResource, ResourceContext, ResourceEnvelope, ResourceOutput } from './declarations.js';
 /**
  * Base API resource — the declarative way to shape what your domain exposes.
  *

package/dist/decorators/ApiResource.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export declare const ApiResource: (alias?: string) => ClassDecorator;

package/dist/decorators/Resources.d.ts

@@ -0,0 +1,27 @@
+import { ResourcesConfig } from '../options/ResourcesBlueprint.js';
+import { ClassType } from '@stone-js/core';
+/**
+ * Options for the `@Resources` decorator: the `stone.resources` bucket, every key optional.
+ */
+export interface ResourcesDecoratorOptions extends ResourcesConfig {
+}
+/**
+ * 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 {}
+ * ```
+ */
+export declare const Resources: <T extends ClassType = ClassType>(options?: ResourcesDecoratorOptions) => ClassDecorator;

package/dist/decorators/Returns.d.ts

@@ -0,0 +1,37 @@
+import { IResource } from '../declarations.js';
+/**
+ * What a handler declares it exposes: a resource, or the alias of a resource class registered with
+ * `@ApiResource`.
+ */
+export type ReturnsInput = IResource<any, any> | string;
+/**
+ * What `@Returns` records for one handler method.
+ */
+export interface ReturnsMetadata {
+    /** The decorated method's name, so the declaration can be found again at request time. */
+    action: string | symbol;
+    /** What that method exposes. */
+    resource: ReturnsInput;
+}
+/**
+ * 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.
+ */
+export declare const Returns: <T extends Function = Function>(resource: ReturnsInput) => MethodDecorator;

package/dist/decorators/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export declare const RETURNS_KEY = "@stone-js/resources/returns";
+/**
+ * Metadata key carrying the alias a resource class registered itself under.
+ */
+export declare const API_RESOURCE_KEY = "@stone-js/resources/resource";

package/dist/defineResource.d.ts

@@ -1,5 +1,5 @@
-import { Resource } from './Resource';
-import { ResourceContext, ResourceOutput } from './declarations';
+import { Resource } from './Resource.js';
+import { ResourceContext, ResourceOutput } from './declarations.js';
 /**
  * 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

package/dist/helpers.d.ts

@@ -1,4 +1,4 @@
-import { ResourceContext, ResourceOutput } from './declarations';
+import { ResourceContext, ResourceOutput } from './declarations.js';
 /**
  * Returns a copy of `object` without any `undefined` values (so conditional fields simply vanish).
  *

package/dist/index.d.ts

@@ -1,4 +1,11 @@
-export * from './Resource';
-export * from './declarations';
-export * from './defineResource';
-export * from './helpers';
+export * from './Resource.js';
+export * from './declarations.js';
+export * from './decorators/ApiResource.js';
+export * from './decorators/Resources.js';
+export * from './decorators/Returns.js';
+export * from './decorators/constants.js';
+export * from './defineResource.js';
+export * from './helpers.js';
+export * from './middleware/BlueprintMiddleware.js';
+export * from './middleware/ResourceRouteMiddleware.js';
+export * from './options/ResourcesBlueprint.js';

package/dist/index.js

@@ -1,3 +1,6 @@
+import { hasMetadata, getMetadata, setClassMetadata, classDecoratorLegacyWrapper, addBlueprint, methodDecoratorLegacyWrapper, addMetadata } from '@stone-js/core';
+import { cloneValue } from '@stone-js/config';
+
 /**
  * Returns a copy of `object` without any `undefined` values (so conditional fields simply vanish).
  *
@@ -188,4 +191,296 @@ function defineResource(transform) {
     }();
 }
 
-export { Resource, applyFields, contextFromEvent, defineResource, except, only, stripUndefined };
+/**
+ * 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';
+
+/**
+ * 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
+};
+
+/**
+ * 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 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.
+ */
+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.
+     *
+     * @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);
+        return (Array.isArray(result) ? resource.collection(result, context) : resource.item(result, context));
+    }
+    /**
+     * 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 and `toArray` can use them, i18n included.
+     *
+     * @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
+};
+
+/**
+ * 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.
+ */
+const ApiResource = (alias) => {
+    return setClassMetadata(API_RESOURCE_KEY, { alias });
+};
+
+/**
+ * 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 { API_RESOURCE_KEY, ApiResource, ApiResourceMiddleware, MetaApiResourceMiddleware, MetaResourceRouteMiddleware, RETURNS_KEY, Resource, ResourceRouteMiddleware, Resources, Returns, applyFields, contextFromEvent, defineResource, except, only, resourcesBlueprint, stripUndefined };

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,85 @@
+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`.
+ */
+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 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.
+ */
+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.
+     *
+     * @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>;
+    /**
+     * 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 and `toArray` can use them, i18n included.
+     *
+     * @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,46 @@
+import { IResource } from '../declarations.js';
+import { AppConfig, StoneBlueprint } from '@stone-js/core';
+/**
+ * Resources configuration bucket (`stone.resources`).
+ */
+export interface ResourcesConfig {
+    /**
+     * 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.7",
+  "version": "0.8.9",
   "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",
@@ -68,6 +68,12 @@
       "beforeEach"
     ]
   },
+  "dependencies": {
+    "@stone-js/config": "0.8.9"
+  },
+  "peerDependencies": {
+    "@stone-js/core": "0.8.9"
+  },
   "scripts": {
     "lint": "ts-standard src",
     "lint:fix": "ts-standard --fix src tests",