@stone-js/resources 0.8.12 → 0.8.14

package/dist/Resource.d.ts

@@ -45,7 +45,7 @@ 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> {
+export declare abstract class Resource<Model = unknown, Output extends ResourceOutput = ResourceOutput, EventType = unknown, PrincipalType = unknown> implements IResource<Model, Output, EventType, PrincipalType> {
     protected checker: IContractChecker;
     protected onViolation: ContractViolationPolicy;
     /**
@@ -68,7 +68,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @param context - The resource context.
      * @returns The schema.
      */
-    abstract schema(context: ResourceContext): ResourceSchema | Promise<ResourceSchema>;
+    abstract schema(context: ResourceContext<EventType, PrincipalType>): ResourceSchema | Promise<ResourceSchema>;
     /**
      * Project one model.
      *
@@ -81,7 +81,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @returns The projected output.
      * @throws {ResourceContractError} When the data breaks the contract and the policy is `throw`.
      */
-    item(model: Model, context?: ResourceContext): Promise<Output>;
+    item(model: Model, context?: ResourceContext<EventType, PrincipalType>): Promise<Output>;
     /**
      * Project a collection.
      *
@@ -93,7 +93,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @param context - The resource context.
      * @returns The projected collection.
      */
-    collection(models: Model[], context?: ResourceContext): Promise<Output[]>;
+    collection(models: Model[], context?: ResourceContext<EventType, PrincipalType>): Promise<Output[]>;
     /**
      * Project into a `{ data, meta }` envelope.
      *
@@ -102,19 +102,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @param meta - Optional metadata (pagination, counts, …).
      * @returns The envelope.
      */
-    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) => Promiseable<unknown>;
-    /**
-     * Named subsets a caller may ask for. Override to expose fragments.
-     */
-    fragments?: (context: ResourceContext) => Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>;
+    response(models: Model | Model[], context?: ResourceContext<EventType, PrincipalType>, meta?: Record<string, unknown>): Promise<ResourceEnvelope<Output | Output[]>>;
     /**
      * The schema to hold this projection against: the requested fragment when the resource exposes one,
      * the full contract otherwise.
@@ -126,7 +114,7 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      * @param context - The resource context.
      * @returns The schema.
      */
-    protected schemaFor(context: ResourceContext): Promise<ResourceSchema>;
+    protected schemaFor(context: ResourceContext<EventType, PrincipalType>): Promise<ResourceSchema>;
     /**
      * Hold the data against the contract, and return what the contract describes.
      *
@@ -158,3 +146,28 @@ export declare abstract class Resource<Model = unknown, Output extends ResourceO
      */
     protected whenIncluded<T>(context: ResourceContext, name: string, value: T | (() => T)): T | undefined;
 }
+/**
+ * The two optional hooks, declared as methods rather than as properties.
+ *
+ * A property-typed function is contravariant on its parameters, and TypeScript refuses a method where
+ * the base declared a property. Between them, those two rules meant a subclass could neither narrow the
+ * context nor write `async data (model, context) {}`, which is the form every example uses. Declared
+ * here, on an interface merged with the class, both forms are accepted and the type parameters actually
+ * reach the signature a subclass writes.
+ */
+export interface Resource<Model, Output extends ResourceOutput, EventType, PrincipalType> {
+    /**
+     * Optional: shape or complete the model before it meets the schema.
+     *
+     * A method signature, deliberately, against the repository's own lint rule: a property-typed
+     * function is contravariant on its parameters, so a subclass narrowing the context was rejected, and
+     * TypeScript separately refuses a method where the base declared a property, so
+     * `async data (model, context) {}` was rejected too. The rule's soundness argument is theoretical for
+     * an extension point; the cost was measured, in an application that could not type its resources.
+     */
+    data?(model: Model, context: ResourceContext<EventType, PrincipalType>): Promiseable<unknown>;
+    /**
+     * Named subsets a caller may ask for. Override to expose fragments.
+     */
+    fragments?(context: ResourceContext<EventType, PrincipalType>): Record<string, ResourceSchema> | Promise<Record<string, ResourceSchema>>;
+}

package/dist/declarations.d.ts

@@ -58,29 +58,29 @@ export interface ResourceEnvelope<T> {
  * 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 = ResourceOutput> {
+export interface IResource<Model = unknown, Output = ResourceOutput, EventType = unknown, PrincipalType = unknown> {
     /** The contract: the schema every projection is validated against and documented from. */
-    schema: (context: ResourceContext) => ResourceSchema | Promise<ResourceSchema>;
+    schema(context: ResourceContext<EventType, PrincipalType>): 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>>;
+    fragments?(context: ResourceContext<EventType, PrincipalType>): 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) => Promiseable<unknown>;
+    data?(model: Model, context: ResourceContext<EventType, PrincipalType>): Promiseable<unknown>;
     /** Project one model. */
-    item: (model: Model, context?: ResourceContext) => Promise<Output>;
+    item(model: Model, context?: ResourceContext<EventType, PrincipalType>): Promise<Output>;
     /** Project a collection. */
-    collection: (models: Model[], context?: ResourceContext) => Promise<Output[]>;
+    collection(models: Model[], context?: ResourceContext<EventType, PrincipalType>): Promise<Output[]>;
     /** Project into a `{ data, meta }` envelope. */
-    response: (models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>) => Promise<ResourceEnvelope<Output | Output[]>>;
+    response(models: Model | Model[], context?: ResourceContext<EventType, PrincipalType>, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/resources",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "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",
@@ -58,7 +58,7 @@
     "typescript": "^5.6.3",
     "vitest": "^3.2.4",
     "zod": "^3.25.76",
-    "@stone-js/service-container": "0.8.12"
+    "@stone-js/service-container": "0.8.14"
   },
   "ts-standard": {
     "globals": [
@@ -71,10 +71,10 @@
     ]
   },
   "dependencies": {
-    "@stone-js/config": "0.8.12"
+    "@stone-js/config": "0.8.14"
   },
   "peerDependencies": {
-    "@stone-js/core": "0.8.12"
+    "@stone-js/core": "0.8.14"
   },
   "scripts": {
     "lint": "ts-standard src",
@@ -83,10 +83,11 @@
     "doc": "typedoc",
     "clean": "rimraf dist",
     "build": "rollup -c",
-    "test": "vitest run",
+    "test": "vitest run && npm run test:types",
     "test:cvg": "npm run test -- --coverage",
     "test:text": "npm run test:cvg -- --coverage.reporter=text",
     "test:html": "npm run test:cvg -- --coverage.reporter=html",
-    "test:clover": "npm run test:cvg -- --coverage.reporter=clover"
+    "test:clover": "npm run test:cvg -- --coverage.reporter=clover",
+    "test:types": "tsc -p tsconfig.types.json"
   }
 }