@stone-js/resources 0.8.10 → 0.8.11

package/dist/Resource.d.ts

@@ -1,3 +1,4 @@
+import { Promiseable } from '@stone-js/core';
 import { IContractChecker } from './ContractChecker.js';
 import { ContractViolationPolicy, IResource, ResourceContext, ResourceEnvelope, ResourceOutput, ResourceSchema } from './declarations.js';
 /**
@@ -33,18 +34,34 @@ import { ContractViolationPolicy, IResource, ResourceContext, ResourceEnvelope,
  * }
  * ```
  */
+/**
+ * What a resource may be handed when the container builds it.
+ *
+ * Only names this module binds itself, because destructuring reads every one of them: a name nothing
+ * bound would throw before the resource ever exists. Configuration is not in here on purpose, it
+ * comes from the blueprint, which is where configuration lives.
+ */
+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> {
-    private readonly checker;
-    private readonly onViolation;
+    protected checker: IContractChecker;
+    protected onViolation: ContractViolationPolicy;
     /**
-     * @param dependencies - Auto-wired services. Nothing is required: this module reads schemas with its
-     *                       own checker, so exposing data never depends on a validation module being
-     *                       enabled. Pass `checker` to substitute a dialect of your own.
+     * @param dependencies - Auto-wired services.
+     *
+     * One name, bound by this module's own blueprint, so the container resolves it like any other service
+     * and this constructor reads it plainly. That is the whole point: a dependency read off a container
+     * that never bound it is not optional, it throws, which is what made every container-resolved
+     * resource fail. The answer was to register the checker, not to test for its presence.
+     *
+     * One name and no more, because destructuring reads each one: a resource must not have to know
+     * which services happen to be bound. The violation policy is configuration, and it travels with the
+     * request in the context, from `stone.resources.onViolation`. Substituting the dialect is a matter
+     * of binding `contractChecker` yourself.
      */
-    constructor(dependencies?: {
-        checker?: IContractChecker;
-        onViolation?: ContractViolationPolicy;
-    });
+    constructor({ contractChecker }?: ResourceDependencies);
     /**
      * The contract: what this resource exposes.
      *
@@ -93,7 +110,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * 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) => unknown | Promise<unknown>;
+    data?: (model: Model, context: ResourceContext) => Promiseable<unknown>;
     /**
      * Named subsets a caller may ask for. Override to expose fragments.
      */

package/dist/declarations.d.ts

@@ -1,3 +1,4 @@
+import { Promiseable } from '@stone-js/core';
 /**
  * A schema, in whatever shape the application already writes them.
  *
@@ -62,7 +63,7 @@ export interface IResource<Model = unknown, Output = ResourceOutput> {
      * 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) => unknown | Promise<unknown>;
+    data?: (model: Model, context: ResourceContext) => Promiseable<unknown>;
     /** Project one model. */
     item: (model: Model, context?: ResourceContext) => Promise<Output>;
     /** Project a collection. */

package/dist/decorators/ApiResource.d.ts

@@ -1,21 +1,30 @@
+import { ClassType } from '@stone-js/core';
 /**
- * Class decorator: register a resource class under a name.
+ * Declare a class as an API resource.
  *
+ * Three statements in one, which is why nothing has to be wired by hand:
+ *
+ * 1. **It is a service.** The container builds it, as a singleton, which means its constructor is
+ *    auto-wired like any other class: whatever it destructures is resolved for it, from the checker
+ *    it holds its contract against to the repository its `data()` needs to complete a model. Nothing
+ *    reads dependencies conditionally, because the container has them.
+ * 2. **It is reachable by name.** The alias is bound in the container as `resource:<name>`, prefixed
+ *    on purpose: an application is free to bind its own `user` service, and a resource named `user`
+ *    must not compete for that name.
+ * 3. **It activates the module.** The blueprint comes with the decorator, so a resource declared this
+ *    way is registered and projected without a second gesture, and `resource: 'user'` on a route
+ *    resolves to this class.
+ *
+ * @param alias - The name a route refers to it by. Defaults to the class name.
+ * @returns A class decorator.
+ *
+ * @example
  * ```ts
  * @ApiResource('user')
  * export class UserResource extends Resource<User> {
- *   toArray (user: User) { return { id: user.id, name: user.name } }
+ *   constructor (private readonly posts: PostRepository) { super() }
+ *   schema (): unknown { return z.object({ id: z.number(), name: z.string() }) }
  * }
  * ```
- *
- * 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;
+export declare const ApiResource: <T extends ClassType = ClassType>(alias?: string) => ClassDecorator;

package/dist/defineResource.d.ts

@@ -1,3 +1,4 @@
+import { Promiseable } from '@stone-js/core';
 import { Resource } from './Resource.js';
 import { IContractChecker } from './ContractChecker.js';
 import { ContractViolationPolicy, ResourceContext, ResourceOutput, ResourceSchema } from './declarations.js';
@@ -12,7 +13,7 @@ export interface ResourceDefinition<Model = unknown> {
     /** Named subsets a caller may ask for, each with its own schema. */
     fragments?: Record<string, ResourceSchema> | ((context: ResourceContext) => Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>);
     /** Optional hook to shape or complete the model before it meets the schema. */
-    data?: (model: Model, context: ResourceContext) => unknown | Promise<unknown>;
+    data?: (model: Model, context: ResourceContext) => Promiseable<unknown>;
 }
 /**
  * The imperative way to define a resource: an object instead of a class.

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 export * from './ContractChecker.js';
-export * from './Resource.js';
 export * from './declarations.js';
 export * from './decorators/ApiResource.js';
+export * from './decorators/constants.js';
 export * from './decorators/Resources.js';
 export * from './decorators/Returns.js';
-export * from './decorators/constants.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

@@ -1,4 +1,4 @@
-import { RuntimeError, setClassMetadata, hasMetadata, getMetadata, classDecoratorLegacyWrapper, addBlueprint, methodDecoratorLegacyWrapper, addMetadata } from '@stone-js/core';
+import { RuntimeError, hasMetadata, getMetadata, classDecoratorLegacyWrapper, setMetadata, SERVICE_KEY, addBlueprint, methodDecoratorLegacyWrapper, addMetadata } from '@stone-js/core';
 import { cloneValue } from '@stone-js/config';
 
 /**
@@ -273,50 +273,25 @@ class ResourceContractError extends RuntimeError {
     }
 }
 
-/**
- * Base API resource — the layer responsible for exposing data.
- *
- * A resource answers two questions, and the second is what makes it worth having. *What leaves?* —
- * and *what did you promise leaves?* The promise is a schema, so the same declaration validates the
- * response, documents it in the published contract, and lets a caller ask for a named subset of it.
- *
- * Projection is the schema's own work: what the schema does not describe is not exposed, so a field
- * added to a model later — a password hash, an internal flag — cannot leak by being forgotten.
- *
- * @example
- * ```ts
- * @ApiResource('user')
- * export class UserResource extends Resource<User> {
- *   constructor ({ posts }: { posts: PostService }) {
- *     super()
- *     this.posts = posts
- *   }
- *
- *   schema () {
- *     return z.object({ id: z.number(), name: z.string(), posts: z.array(z.string()).optional() })
- *   }
- *
- *   fragments () {
- *     return { summary: z.object({ id: z.number(), name: z.string() }) }
- *   }
- *
- *   async data (user: User) {
- *     return { ...user, posts: await this.posts.titlesOf(user.id) }
- *   }
- * }
- * ```
- */
 class Resource {
     checker;
     onViolation;
     /**
-     * @param dependencies - Auto-wired services. Nothing is required: this module reads schemas with its
-     *                       own checker, so exposing data never depends on a validation module being
-     *                       enabled. Pass `checker` to substitute a dialect of your own.
+     * @param dependencies - Auto-wired services.
+     *
+     * One name, bound by this module's own blueprint, so the container resolves it like any other service
+     * and this constructor reads it plainly. That is the whole point: a dependency read off a container
+     * that never bound it is not optional, it throws, which is what made every container-resolved
+     * resource fail. The answer was to register the checker, not to test for its presence.
+     *
+     * One name and no more, because destructuring reads each one: a resource must not have to know
+     * which services happen to be bound. The violation policy is configuration, and it travels with the
+     * request in the context, from `stone.resources.onViolation`. Substituting the dialect is a matter
+     * of binding `contractChecker` yourself.
      */
-    constructor(dependencies = {}) {
-        this.checker = dependencies.checker ?? ContractChecker.create();
-        this.onViolation = dependencies.onViolation ?? 'throw';
+    constructor({ contractChecker } = {}) {
+        this.checker = contractChecker ?? ContractChecker.create();
+        this.onViolation = 'throw';
     }
     /**
      * Project one model.
@@ -472,7 +447,18 @@ class Resource {
  * ```
  */
 function defineResource(definition, dependencies = {}) {
+    // Assigned after construction, not through it: the class constructor is the container's, and it
+    // only reads names this module binds. An explicit object is the imperative form's business.
     const resource = new class extends Resource {
+        constructor() {
+            super();
+            if (dependencies.checker !== undefined) {
+                this.checker = dependencies.checker;
+            }
+            if (dependencies.onViolation !== undefined) {
+                this.onViolation = dependencies.onViolation;
+            }
+        }
         async schema(context) {
             if (typeof definition.schema !== 'function') {
                 return definition.schema;
@@ -480,7 +466,7 @@ function defineResource(definition, dependencies = {}) {
             const build = definition.schema;
             return await build(context);
         }
-    }(dependencies);
+    }();
     if (definition.fragments !== undefined) {
         const declared = definition.fragments;
         resource.fragments = async (context) => {
@@ -508,30 +494,6 @@ const RETURNS_KEY = '@stone-js/resources/returns';
  */
 const API_RESOURCE_KEY = '@stone-js/resources/resource';
 
-/**
- * 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 });
-};
-
 /**
  * Route middleware: shapes what a route returns, after its handler ran.
  *
@@ -690,7 +652,9 @@ class ResourceRouteMiddleware {
             return entry;
         }
         const ResourceClass = entry;
-        return this.container?.resolve?.(ResourceClass, true) ?? new ResourceClass({});
+        // `resolve(Class, true)` uses the binding `@ApiResource` declared, and binds it as a singleton
+        // when there is none, so a resource is built once with its dependencies wired either way.
+        return this.container?.resolve?.(ResourceClass, true) ?? new ResourceClass();
     }
 }
 /**
@@ -755,9 +719,24 @@ const MetaApiResourceMiddleware = {
  * export const Application = defineStoneApp({ name: 'my-app' }, [resourcesBlueprint])
  * ```
  */
+/**
+ * The reader every resource holds its contract against, as a service.
+ *
+ * Bound so a resource's constructor can simply ask for it. A dependency read off the container that
+ * nothing ever bound is not optional, it is a crash, which is what made every container-resolved
+ * resource fail on a service nobody was told to register. The fix is the registration, not a
+ * conditional read.
+ */
+const MetaContractChecker = {
+    module: ContractChecker,
+    isClass: true,
+    singleton: true,
+    alias: 'contractChecker'
+};
 const resourcesBlueprint = {
     stone: {
         resources: {},
+        services: [MetaContractChecker],
         blueprint: {
             middleware: [
                 MetaApiResourceMiddleware
@@ -771,6 +750,49 @@ const resourcesBlueprint = {
     }
 };
 
+/**
+ * Declare a class as an API resource.
+ *
+ * Three statements in one, which is why nothing has to be wired by hand:
+ *
+ * 1. **It is a service.** The container builds it, as a singleton, which means its constructor is
+ *    auto-wired like any other class: whatever it destructures is resolved for it, from the checker
+ *    it holds its contract against to the repository its `data()` needs to complete a model. Nothing
+ *    reads dependencies conditionally, because the container has them.
+ * 2. **It is reachable by name.** The alias is bound in the container as `resource:<name>`, prefixed
+ *    on purpose: an application is free to bind its own `user` service, and a resource named `user`
+ *    must not compete for that name.
+ * 3. **It activates the module.** The blueprint comes with the decorator, so a resource declared this
+ *    way is registered and projected without a second gesture, and `resource: 'user'` on a route
+ *    resolves to this class.
+ *
+ * @param alias - The name a route refers to it by. Defaults to the class name.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```ts
+ * @ApiResource('user')
+ * export class UserResource extends Resource<User> {
+ *   constructor (private readonly posts: PostRepository) { super() }
+ *   schema (): unknown { return z.object({ id: z.number(), name: z.string() }) }
+ * }
+ * ```
+ */
+const ApiResource = (alias) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        const name = alias ?? target.name;
+        setMetadata(context, API_RESOURCE_KEY, { alias: name });
+        setMetadata(context, SERVICE_KEY, { singleton: true, isClass: true, alias: `resource:${name}` });
+        addBlueprint(target, context, resourcesBlueprint, {
+            stone: {
+                resources: {
+                    registry: { [name]: target }
+                }
+            }
+        });
+    });
+};
+
 /**
  * Class decorator: shape what routes return, declaratively.
  *
@@ -827,4 +849,4 @@ const Returns = (resource) => {
     });
 };
 
-export { API_RESOURCE_KEY, ApiResource, ApiResourceMiddleware, ContractChecker, MetaApiResourceMiddleware, MetaResourceRouteMiddleware, RETURNS_KEY, Resource, ResourceContractError, ResourceRouteMiddleware, Resources, Returns, applyFields, contextFromEvent, defineResource, except, only, resourcesBlueprint, stripUndefined };
+export { API_RESOURCE_KEY, ApiResource, ApiResourceMiddleware, ContractChecker, MetaApiResourceMiddleware, MetaContractChecker, MetaResourceRouteMiddleware, RETURNS_KEY, Resource, ResourceContractError, ResourceRouteMiddleware, Resources, Returns, applyFields, contextFromEvent, defineResource, except, only, resourcesBlueprint, stripUndefined };

package/dist/options/ResourcesBlueprint.d.ts

@@ -1,5 +1,5 @@
 import { IResource } from '../declarations.js';
-import { AppConfig, StoneBlueprint } from '@stone-js/core';
+import { AppConfig, MetaService, StoneBlueprint } from '@stone-js/core';
 /**
  * Resources configuration bucket (`stone.resources`).
  */
@@ -62,4 +62,13 @@ export interface ResourcesBlueprint extends StoneBlueprint {
  * export const Application = defineStoneApp({ name: 'my-app' }, [resourcesBlueprint])
  * ```
  */
+/**
+ * The reader every resource holds its contract against, as a service.
+ *
+ * Bound so a resource's constructor can simply ask for it. A dependency read off the container that
+ * nothing ever bound is not optional, it is a crash, which is what made every container-resolved
+ * resource fail on a service nobody was told to register. The fix is the registration, not a
+ * conditional read.
+ */
+export declare const MetaContractChecker: MetaService;
 export declare const resourcesBlueprint: ResourcesBlueprint;

package/package.json

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