@stone-js/resources 0.8.9 → 0.8.10

package/dist/ContractChecker.d.ts

@@ -0,0 +1,96 @@
+import { ContractIssue } from './errors/ResourceContractError.js';
+/** What checking a projection against its contract produced. */
+export interface ContractResult<T = unknown> {
+    success: boolean;
+    value?: T;
+    issues?: ContractIssue[];
+}
+/**
+ * What this module needs from a schema: the ability to run it and read the outcome.
+ *
+ * Declared so an application can substitute its own — a bespoke dialect, a shared engine it already
+ * configured — without this module knowing anything about it.
+ */
+export interface IContractChecker {
+    check: <T>(schema: unknown, data: unknown) => ContractResult<T>;
+}
+/**
+ * Runs a schema and reports what it said.
+ *
+ * This module reads schemas; it does not validate requests, own engines, or keep a registry — so it
+ * carries its own reader rather than depending on a validation module to project data. The dialects
+ * it accepts are public specifications, not one library's API: Standard Schema first, then the
+ * `safeParse`/`parse` shape, then a plain `validate`. An application writes its schemas once and both
+ * sides of the boundary read them.
+ *
+ * Substitutable: pass your own {@link IContractChecker} and this one steps aside.
+ */
+export declare class ContractChecker implements IContractChecker {
+    /**
+     * Factory.
+     *
+     * @returns A checker.
+     */
+    static create(): ContractChecker;
+    /**
+     * Run a schema against a value.
+     *
+     * @param schema - The contract.
+     * @param data - What the resource produced.
+     * @returns Whether it holds, the parsed value, and what failed.
+     * @throws {TypeError} When the value is not a schema this can run, because guessing would mean
+     *                     projecting unchecked data while reporting success.
+     */
+    check<T>(schema: unknown, data: unknown): ContractResult<T>;
+    /**
+     * Read a Standard Schema result.
+     *
+     * The synchronous path only: a schema whose validation is asynchronous returns a promise, and a
+     * promise is not a result. Saying so beats treating it as one, which is how `[object Promise]`
+     * reaches a response body.
+     *
+     * @param schema - The schema.
+     * @param data - The value.
+     * @returns The outcome.
+     */
+    private fromStandard;
+    /**
+     * Read a `safeParse` result (the Zod-like shape).
+     *
+     * @param schema - The schema.
+     * @param data - The value.
+     * @returns The outcome.
+     */
+    private fromSafeParse;
+    /**
+     * Read a native `validate` result: already the shape this module reports.
+     *
+     * @param schema - The schema.
+     * @param data - The value.
+     * @returns The outcome.
+     */
+    private fromValidate;
+    /**
+     * Read a throwing `parse`.
+     *
+     * @param schema - The schema.
+     * @param data - The value.
+     * @returns The outcome.
+     */
+    private fromParse;
+    /**
+     * Normalise one issue, whatever dialect reported it.
+     *
+     * @param issue - The raw issue.
+     * @returns The issue.
+     */
+    private toIssue;
+    /** @param schema - The candidate. @returns Whether it speaks Standard Schema. */
+    private isStandard;
+    /** @param schema - The candidate. @returns Whether it exposes `safeParse`. */
+    private hasSafeParse;
+    /** @param schema - The candidate. @returns Whether it exposes `validate`. */
+    private hasValidate;
+    /** @param schema - The candidate. @returns Whether it exposes `parse`. */
+    private hasParse;
+}

package/dist/Resource.d.ts

@@ -1,62 +1,130 @@
-import { IResource, ResourceContext, ResourceEnvelope, ResourceOutput } from './declarations.js';
+import { IContractChecker } from './ContractChecker.js';
+import { ContractViolationPolicy, IResource, ResourceContext, ResourceEnvelope, ResourceOutput, ResourceSchema } from './declarations.js';
 /**
- * Base API resource — the declarative way to shape what your domain exposes.
+ * Base API resource — the layer responsible for exposing data.
  *
- * Extend it and implement {@link Resource.toArray} to map a model to its public shape. Everything
- * else (sparse fieldsets, dropping conditional fields, collections, envelopes) is handled for you.
- * A resource is decoupled from controllers and platform-agnostic: the same resource shapes data on
- * the backend and on the frontend.
+ * 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
- * class UserResource extends Resource<User> {
- *   toArray (user: User, ctx: ResourceContext) {
- *     return {
- *       id: user.id,
- *       name: user.name,
- *       email: this.when(ctx.self === true, user.email),
- *       posts: this.whenIncluded(ctx, 'posts', () => postResource.collection(user.posts))
- *     }
+ * @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) }
  *   }
  * }
  * ```
  */
 export declare abstract class Resource<Model = unknown, Output extends ResourceOutput = ResourceOutput> implements IResource<Model, Output> {
+    private readonly checker;
+    private readonly onViolation;
     /**
-     * Map a model to its public shape (before field filtering).
+     * @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.
+     */
+    constructor(dependencies?: {
+        checker?: IContractChecker;
+        onViolation?: ContractViolationPolicy;
+    });
+    /**
+     * The contract: what this resource exposes.
      *
-     * @param model - The domain model.
      * @param context - The resource context.
-     * @returns The public shape.
+     * @returns The schema.
      */
-    abstract toArray(model: Model, context: ResourceContext): Output;
+    abstract schema(context: ResourceContext): ResourceSchema | Promise<ResourceSchema>;
     /**
-     * Transform one model, applying the requested sparse fieldset and dropping undefined fields.
+     * Project one model.
+     *
+     * The order is the design: complete the data, choose the contract the caller asked for, hold the
+     * result against it, then narrow. Validation happens *before* narrowing, so the promise is checked
+     * against everything the resource produced rather than against whatever survived a query parameter.
      *
      * @param model - The domain model.
      * @param context - The resource context.
-     * @returns The filtered public shape.
+     * @returns The projected output.
+     * @throws {ResourceContractError} When the data breaks the contract and the policy is `throw`.
      */
-    item(model: Model, context?: ResourceContext): Partial<Output>;
+    item(model: Model, context?: ResourceContext): Promise<Output>;
     /**
-     * Transform a collection of models.
+     * Project a collection.
+     *
+     * Sequential rather than concurrent: `data()` may reach a database or an API, and a hundred models
+     * turning into a hundred simultaneous calls is a denial of service an application performs on
+     * itself. A resource that wants concurrency batches inside its own `data()`, where it knows the cost.
      *
      * @param models - The domain models.
      * @param context - The resource context.
-     * @returns The transformed collection.
+     * @returns The projected collection.
      */
-    collection(models: Model[], context?: ResourceContext): Array<Partial<Output>>;
+    collection(models: Model[], context?: ResourceContext): Promise<Output[]>;
     /**
-     * Wrap a model or a collection in a `{ data, meta }` envelope.
+     * Project into a `{ data, meta }` envelope.
      *
      * @param models - A model or a collection.
      * @param context - The resource context.
      * @param meta - Optional metadata (pagination, counts, …).
      * @returns The envelope.
      */
-    response(models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>): ResourceEnvelope<Partial<Output> | Array<Partial<Output>>>;
+    response(models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>): Promise<ResourceEnvelope<Output | Output[]>>;
+    /**
+     * Optional: shape or complete the model before it meets the schema.
+     *
+     * `declare`, not a field: an uninitialised class field is *defined* as `undefined` on the instance,
+     * 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>;
+    /**
+     * Named subsets a caller may ask for. Override to expose fragments.
+     */
+    fragments?: (context: ResourceContext) => Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>;
+    /**
+     * The schema to hold this projection against: the requested fragment when the resource exposes one,
+     * the full contract otherwise.
+     *
+     * An unknown fragment falls back to the full contract rather than failing. A caller guessing
+     * `?view=nonsense` is asking a question, not attacking: answering the documented shape is more
+     * useful than a 500, and the fragments a resource exposes are published in the contract anyway.
+     *
+     * @param context - The resource context.
+     * @returns The schema.
+     */
+    protected schemaFor(context: ResourceContext): Promise<ResourceSchema>;
+    /**
+     * Hold the data against the contract, and return what the contract describes.
+     *
+     * The schema is the projection: its parsed value is the output, so a field the contract does not
+     * mention is not exposed, whatever the model gains later.
+     *
+     * @param data - The completed data.
+     * @param schema - The contract.
+     * @param context - The resource context.
+     * @returns The projected value.
+     * @throws {ResourceContractError} When the data breaks the contract and the policy is `throw`.
+     */
+    protected project(data: unknown, schema: ResourceSchema, context: ResourceContext): Promise<unknown>;
     /**
-     * Include a value only when `condition` is truthy (otherwise the field is dropped).
+     * Include a value only when `condition` holds (otherwise the field is dropped).
      *
      * @param condition - Whether to include the value.
      * @param value - The value, or a lazy factory (only evaluated when included).
@@ -64,7 +132,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      */
     protected when<T>(condition: boolean, value: T | (() => T)): T | undefined;
     /**
-     * Include a value only when the relation was requested via `context.include`.
+     * Include a value only when the relation was requested through `context.include`.
      *
      * @param context - The resource context.
      * @param name - The relation name.

package/dist/declarations.d.ts

@@ -1,36 +1,74 @@
 /**
- * The context that shapes a transformation: which fields the client asked for, which relations to
- * include, and any extra data (the current user, the event, …) a resource may consult.
+ * A schema, in whatever shape the application already writes them.
  *
- * It is intentionally open so resources can read whatever they need while staying agnostic.
+ * Anything `@stone-js/validation` accepts is accepted here: a Standard Schema (Zod, Valibot, ArkType
+ * and others), a Zod-like `safeParse`, or a native Stone.js schema. Resources do not define a schema
+ * language; they use the one the application already validates its input with, so a contract is
+ * written once in one dialect on both sides of the boundary.
+ */
+export type ResourceSchema = unknown;
+/**
+ * The context a projection is given.
+ *
+ * Open on purpose: a resource reads whatever it needs, and the middleware fills in what the request
+ * 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 — when set, the output is limited to these top-level keys. */
+    /** Requested sparse fieldset — narrows the output to these top-level keys. */
     fields?: string[];
     /** Requested relations to embed. */
     include?: string[];
-    /** Anything else a resource needs (e.g. the authenticated principal). */
+    /** 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;
+    /** Anything else a resource needs. */
     [key: string]: unknown;
 }
 /** A plain, serialisable output object. */
 export type ResourceOutput = Record<string, unknown>;
 /**
- * A `{ data, meta }` envelope around a transformed item or collection.
+ * A `{ data, meta }` envelope around a projected item or collection.
  */
 export interface ResourceEnvelope<T> {
     data: T;
     meta?: Record<string, unknown>;
 }
 /**
- * The resource contract: transform a model (or a collection) into its public representation.
+ * What a resource does: turn a domain model into the shape a caller is allowed to see, and say what
+ * that shape is.
+ *
+ * Saying it is the point. A projection written as code answers "what does this return?" only by being
+ * read and trusted; a projection written as a schema answers it to a person, to `@stone-js/openapi`,
+ * and to the resource itself, which validates against it before anything leaves. One declaration, three
+ * consumers, and no way for the documentation to drift from the response.
  */
-export interface IResource<Model = unknown, Output extends ResourceOutput = ResourceOutput> {
-    /** Transform one model into its public shape (before field filtering). */
-    toArray: (model: Model, context: ResourceContext) => Output;
-    /** Transform one model, applying sparse fieldsets and dropping undefined fields. */
-    item: (model: Model, context?: ResourceContext) => Partial<Output>;
-    /** Transform a collection. */
-    collection: (models: Model[], context?: ResourceContext) => Array<Partial<Output>>;
-    /** Wrap a model or collection in a `{ data, meta }` envelope. */
-    response: (models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>) => ResourceEnvelope<Partial<Output> | Array<Partial<Output>>>;
+export interface IResource<Model = unknown, Output = ResourceOutput> {
+    /** The contract: the schema every projection is validated against and documented from. */
+    schema: (context: ResourceContext) => ResourceSchema | Promise<ResourceSchema>;
+    /**
+     * Named subsets a caller may ask for, each with its own schema.
+     *
+     * A fragment is not a filter: it is a contract of its own, documented and validated like the full
+     * one. That is what makes `?view=summary` safe to expose.
+     */
+    fragments?: (context: ResourceContext) => Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>;
+    /**
+     * Optional hook to shape or complete the model before it meets the schema.
+     *
+     * 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>;
+    /** Project one model. */
+    item: (model: Model, context?: ResourceContext) => Promise<Output>;
+    /** Project a collection. */
+    collection: (models: Model[], context?: ResourceContext) => Promise<Output[]>;
+    /** Project into a `{ data, meta }` envelope. */
+    response: (models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>) => Promise<ResourceEnvelope<Output | Output[]>>;
 }
+/** What to do when the data does not match the contract the resource published. */
+export type ContractViolationPolicy = 'throw' | 'warn';

package/dist/defineResource.d.ts

@@ -1,17 +1,39 @@
 import { Resource } from './Resource.js';
-import { ResourceContext, ResourceOutput } from './declarations.js';
+import { IContractChecker } from './ContractChecker.js';
+import { ContractViolationPolicy, ResourceContext, ResourceOutput, ResourceSchema } 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
- * sparse fieldsets for free).
+ * What an imperatively-defined resource declares.
  *
- * @param transform - Maps a model to its public shape.
+ * The same three things a class declares, so neither paradigm can do something the other cannot.
+ */
+export interface ResourceDefinition<Model = unknown> {
+    /** The contract: what this resource exposes. A schema, or a function returning one. */
+    schema: ResourceSchema | ((context: ResourceContext) => ResourceSchema | Promise<ResourceSchema>);
+    /** 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>;
+}
+/**
+ * The imperative way to define a resource: an object instead of a class.
+ *
+ * Parity is the rule, so this declares exactly what a class declares and gets exactly what a class
+ * gets. It needs nothing injected: this module reads schemas with its own checker.
+ *
+ * @param definition - The schema, and optionally fragments and a `data()` hook.
+ * @param dependencies - Optional explicit services, for a resource used outside a request.
  * @returns A resource.
  *
  * @example
  * ```ts
- * const userResource = defineResource<User>((user) => ({ id: user.id, name: user.name }))
- * userResource.collection(users, { fields: ['id'] })
+ * export const userResource = defineResource<User>({
+ *   schema: z.object({ id: z.number(), name: z.string() }),
+ *   fragments: { summary: z.object({ id: z.number() }) },
+ *   data: async (user) => ({ ...user, posts: await posts.titlesOf(user.id) })
+ * })
  * ```
  */
-export declare function defineResource<Model = unknown, Output extends ResourceOutput = ResourceOutput>(transform: (model: Model, context: ResourceContext) => Output): Resource<Model, Output>;
+export declare function defineResource<Model = unknown, Output extends ResourceOutput = ResourceOutput>(definition: ResourceDefinition<Model>, dependencies?: {
+    checker?: IContractChecker;
+    onViolation?: ContractViolationPolicy;
+}): Resource<Model, Output>;

package/dist/errors/ResourceContractError.d.ts

@@ -0,0 +1,31 @@
+import { ErrorOptions, RuntimeError } from '@stone-js/core';
+/** One reason the data did not match the contract. */
+export interface ContractIssue {
+    message: string;
+    path: Array<string | number>;
+}
+/** Options carrying what failed. */
+export interface ResourceContractErrorOptions extends ErrorOptions {
+    issues?: ContractIssue[];
+}
+/**
+ * Raised when what a handler produced does not match the schema its resource published.
+ *
+ * This is a server-side fault, deliberately. The resource's schema is a promise made to every caller
+ * and to the published contract; data that breaks it means the application is about to answer
+ * something it documented it would not. Returning it anyway is the failure — a client cannot detect
+ * it, and a consumer generated from the contract will break on a field that was supposed to be there.
+ *
+ * It fires on a genuine breach, not on a difference: a schema strips what it does not describe, so
+ * extra fields are simply not exposed. Reaching this means something the contract requires is missing
+ * or has the wrong type.
+ */
+export declare class ResourceContractError extends RuntimeError {
+    /** What failed, so a log says which field rather than "validation failed". */
+    readonly issues: ContractIssue[];
+    /**
+     * @param message - What went wrong.
+     * @param options - Additional error options, including the issues.
+     */
+    constructor(message: string, options?: ResourceContractErrorOptions);
+}

package/dist/helpers.d.ts

@@ -32,13 +32,26 @@ export declare function except<T extends ResourceOutput>(object: T, keys: string
  */
 export declare function applyFields<T extends ResourceOutput>(output: T, fields?: string[]): Partial<T>;
 /**
- * Builds a {@link ResourceContext} from an incoming event's `fields` and `include` query
- * parameters (comma-separated). Agnostic: the event only needs a `get(key)` method.
+ * Build a {@link ResourceContext} from an incoming event.
+ *
+ * The parameter names are configuration, not convention: an API that already answers `?view=` or
+ * `?only=` keeps its own vocabulary instead of gaining a second one. Defaults are `fields`, `include`
+ * and `view`.
+ *
+ * The authenticated principal is read too, because deciding what a caller may see is the most common
+ * reason two callers get different shapes — and a resource that cannot see who is asking has to be
+ * told by the handler, which is exactly the plumbing this module exists to remove.
+ *
+ * Agnostic: the event only needs `get(key)`.
  *
  * @param event - Anything with `get(key)` (an `IncomingHttpEvent`, a URL search wrapper, …).
+ * @param blueprint - The blueprint carrying the parameter names, when there is one.
  * @param extra - Extra context to merge in.
  * @returns The resource context.
  */
 export declare function contextFromEvent(event: {
     get: <T>(key: string, fallback?: T) => T;
+    getUser?: <T>() => T;
+}, blueprint?: {
+    get: <T>(key: string, fallback?: T) => T;
 }, extra?: ResourceContext): ResourceContext;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './ContractChecker.js';
 export * from './Resource.js';
 export * from './declarations.js';
 export * from './decorators/ApiResource.js';
@@ -5,6 +6,7 @@ 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';