@furystack/rest 10.0.0 → 10.0.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [10.0.1] - 2026-05-21
+
+### 📚 Documentation
+
+- Rewrote JSDoc on the endpoint models (`GetEndpoint`, `GetCollectionEndpoint`, `PostEndpoint`, `PatchEndpoint`, `DeleteEndpoint`), `ApiEndpointSchema`, `RequestError`, and the (de)serialize helpers to follow the new value-test guidance: dropped restate-the-type narration, kept intent / trade-offs / constraints (e.g. how `Validate()` and `Authenticate()` populate the schema metadata).
+
+### ⬆️ Dependencies
+
+- Bump dev `vitest` to `^4.1.5`.
+- Bumped `@types/node` to `^25.9.1` and `vitest` to `^4.1.7`. No source changes — dev-tooling bump only.
+
 ## [10.0.0] - 2026-04-25
 
 ### 💥 Breaking Changes

package/esm/api-endpoint-schema.d.ts

@@ -12,49 +12,27 @@ import type { RestApi } from './rest-api.js';
  */
 export type Schema = unknown;
 /**
- * Represents the definition of an API endpoint, including its path, schema, and schema name.
- * The HTTP method is now implicit in the structure key.
+ * Reflection metadata for a single endpoint. Populated by the wrappers
+ * applied at definition time (`Validate()`, `Authenticate()`) and read by
+ * `generateOpenApiDocument` and the `/schema` action. The HTTP method is
+ * implicit in the parent {@link ApiEndpointSchema} structure key.
  */
 export type ApiEndpointDefinition = {
-    /**
-     * The path of the endpoint, which is the URL pattern that the endpoint responds to.
-     */
     path: string;
-    /**
-     * The JSON schema that defines the structure of the request and response for this endpoint.
-     * To include a schema, wrap your endpoint with a Validate({...}) call during the implementation.
-     */
+    /** Populated by `Validate({ schema })`. Empty string when missing. */
     schema: Schema;
-    /**
-     * The name of the schema, which can be used to reference this schema in documentation or other contexts.
-     * To include a schema name, wrap your endpoint with a Validate({...}) call during the implementation.
-     */
+    /** Populated by `Validate({ schemaName })`. Empty string when missing. */
     schemaName: string;
-    /**
-     * Indicates whether the endpoint requires authentication.
-     * To include the flag, wrap your endpoint with an Authenticate() call during the implementation.
-     */
+    /** Populated by `Authenticate()` wrapping the action. */
     isAuthenticated: boolean;
-    /**
-     * Tags for API documentation grouping.
-     */
     tags?: string[];
-    /**
-     * Marks the endpoint as deprecated.
-     */
     deprecated?: boolean;
-    /**
-     * A short summary of the endpoint.
-     */
     summary?: string;
-    /**
-     * A longer description of the endpoint.
-     */
     description?: string;
     /**
-     * The OpenAPI security scheme names required for this endpoint.
-     * When present, used by `generateOpenApiDocument` to emit accurate per-operation `security`.
-     * When absent, falls back to the `isAuthenticated` boolean behavior.
+     * OpenAPI security scheme names required for this endpoint. Populated by
+     * `Authorize()` and friends. When present overrides the
+     * `isAuthenticated` boolean fallback in `generateOpenApiDocument`.
      */
     securitySchemes?: string[];
 };

package/esm/api-endpoint-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-endpoint-schema.d.ts","sourceRoot":"","sources":["../src/api-endpoint-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EACV,aAAa,EACb,2BAA2B,EAC3B,aAAa,EACb,oBAAoB,EACpB,YAAY,EACZ,SAAS,EACV,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,CAAA;AAE5B;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAA;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;IACxB,IAAI,CAAC,EAAE,SAAS,EAAE,CAAA;IAClB,YAAY,CAAC,EAAE,2BAA2B,CAAA;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;CACvD,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,IAAI;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,SAAS,EAAE;SACR,OAAO,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,SAAS,MAAM,IAAI,GAC5C,IAAI,CAAC,OAAO,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C;aAAG,KAAK,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,qBAAqB;SAAE,GAClE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC;KAC1C,CAAA;CACF,CAAA"}
+{"version":3,"file":"api-endpoint-schema.d.ts","sourceRoot":"","sources":["../src/api-endpoint-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EACV,aAAa,EACb,2BAA2B,EAC3B,aAAa,EACb,oBAAoB,EACpB,YAAY,EACZ,SAAS,EACV,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAA;IAClB,yDAAyD;IACzD,eAAe,EAAE,OAAO,CAAA;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;IACxB,IAAI,CAAC,EAAE,SAAS,EAAE,CAAA;IAClB,YAAY,CAAC,EAAE,2BAA2B,CAAA;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;CACvD,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,IAAI;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,SAAS,EAAE;SACR,OAAO,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,SAAS,MAAM,IAAI,GAC5C,IAAI,CAAC,OAAO,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C;aAAG,KAAK,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,qBAAqB;SAAE,GAClE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC;KAC1C,CAAA;CACF,CAAA"}

package/esm/deserialize-query-string.d.ts

@@ -1,9 +1,14 @@
 /**
- * Decodes a URL-safe base64 encoded JSON string back to its original value
- * Decoding steps: See the encoding steps in reverse order
- * @param value The value to decode
- * @returns The decoded value
+ * Reverses the encoding produced by `serializeValue`. Throws a 400
+ * {@link RequestError} on malformed input — surfaces to clients as a
+ * "bad request" rather than crashing the server.
  */
 export declare const decode: <T>(value: string) => T;
-export declare const deserializeQueryString: (fullQueryString: string) => Record<string, unknown>;
+/**
+ * Decodes a query string into a typed object. Empty keys/values are
+ * skipped. Each surviving value is deserialized via {@link decode}.
+ */
+export declare const deserializeQueryString: (fullQueryString: string) => {
+    [k: string]: unknown;
+};
 //# sourceMappingURL=deserialize-query-string.d.ts.map

package/esm/deserialize-query-string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deserialize-query-string.d.ts","sourceRoot":"","sources":["../src/deserialize-query-string.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,OAAO,MAAM,KAAG,CAMzC,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,iBAAiB,MAAM,KAKvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAC5D,CAAA"}
+{"version":3,"file":"deserialize-query-string.d.ts","sourceRoot":"","sources":["../src/deserialize-query-string.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,OAAO,MAAM,KAAG,CAMzC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,iBAAiB,MAAM;;CAM7D,CAAA"}

package/esm/deserialize-query-string.js

@@ -1,9 +1,8 @@
 import { RequestError } from './request-error.js';
 /**
- * Decodes a URL-safe base64 encoded JSON string back to its original value
- * Decoding steps: See the encoding steps in reverse order
- * @param value The value to decode
- * @returns The decoded value
+ * Reverses the encoding produced by `serializeValue`. Throws a 400
+ * {@link RequestError} on malformed input — surfaces to clients as a
+ * "bad request" rather than crashing the server.
  */
 export const decode = (value) => {
     try {
@@ -13,6 +12,10 @@ export const decode = (value) => {
         throw new RequestError('Failed to decode query parameter value', 400);
     }
 };
+/**
+ * Decodes a query string into a typed object. Empty keys/values are
+ * skipped. Each surviving value is deserialized via {@link decode}.
+ */
 export const deserializeQueryString = (fullQueryString) => {
     const params = [...new URLSearchParams(fullQueryString).entries()]
         .filter(([key, value]) => key && value)

package/esm/deserialize-query-string.js.map

@@ -1 +1 @@
-{"version":3,"file":"deserialize-query-string.js","sourceRoot":"","sources":["../src/deserialize-query-string.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAI,KAAa,EAAK,EAAE;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAM,CAAA;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,YAAY,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAA;IACvE,CAAC;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,eAAuB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,eAAe,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/D,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAU,CAAC,CAAA;IAEvD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAA4B,CAAA;AAC9D,CAAC,CAAA"}
+{"version":3,"file":"deserialize-query-string.js","sourceRoot":"","sources":["../src/deserialize-query-string.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAI,KAAa,EAAK,EAAE;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAM,CAAA;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,YAAY,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAA;IACvE,CAAC;AACH,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,eAAuB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,eAAe,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/D,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAU,CAAC,CAAA;IAEvD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;AACnC,CAAC,CAAA"}

package/esm/endpoint-models/delete-endpoint.d.ts

@@ -1,6 +1,4 @@
-/**
- * Endpoint model for deleting entities
- */
+/** DELETE-by-id endpoint contract. */
 export type DeleteEndpoint<T, TPrimaryKey extends keyof T> = {
     url: {
         id: T[TPrimaryKey];

package/esm/endpoint-models/delete-endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/delete-endpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,IAAI;IAC3D,GAAG,EAAE;QAAE,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;CACf,CAAA"}
+{"version":3,"file":"delete-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/delete-endpoint.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,IAAI;IAC3D,GAAG,EAAE;QAAE,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;CACf,CAAA"}

package/esm/endpoint-models/get-collection-endpoint.d.ts

@@ -1,20 +1,13 @@
 import type { FindOptions } from '@furystack/core';
 /**
- * Response Model for GetCollection
+ * Collection result. `count` is the **total** matching entity count
+ * (ignores `top` / `skip`); `entries` is the page returned for this query.
  */
 export type GetCollectionResult<T> = {
-    /**
-     * The Total count of entities
-     */
     count: number;
-    /**
-     * List of the selected entities
-     */
     entries: T[];
 };
-/**
- * Rest endpoint model for getting / querying collections
- */
+/** GET-collection endpoint contract. */
 export type GetCollectionEndpoint<T> = {
     query: {
         findOptions?: FindOptions<T, Array<keyof T>>;

package/esm/endpoint-models/get-collection-endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-collection-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/get-collection-endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IACnC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,OAAO,EAAE,CAAC,EAAE,CAAA;CACb,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;IACrC,KAAK,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;KAAE,CAAA;IACvD,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAA;CAC/B,CAAA"}
+{"version":3,"file":"get-collection-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/get-collection-endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,CAAC,EAAE,CAAA;CACb,CAAA;AAED,wCAAwC;AACxC,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;IACrC,KAAK,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;KAAE,CAAA;IACvD,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAA;CAC/B,CAAA"}

package/esm/endpoint-models/get-endpoint.d.ts

@@ -1,17 +1,9 @@
-/**
- * Endpoint model for getting a single entity
- */
+/** GET-by-id endpoint contract. `select` narrows the projected fields. */
 export type GetEntityEndpoint<T, TPrimaryKey extends keyof T> = {
     query: {
-        /**
-         * The list of fields to select
-         */
         select?: Array<keyof T>;
     };
     url: {
-        /**
-         * The entity's unique identifier
-         */
         id: T[TPrimaryKey];
     };
     result: T;

package/esm/endpoint-models/get-endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/get-endpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,IAAI;IAC9D,KAAK,EAAE;QACL;;WAEG;QACH,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;KACxB,CAAA;IACD,GAAG,EAAE;QACH;;WAEG;QACH,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAA;KACnB,CAAA;IACD,MAAM,EAAE,CAAC,CAAA;CACV,CAAA"}
+{"version":3,"file":"get-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/get-endpoint.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,IAAI;IAC9D,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;KAAE,CAAA;IAClC,GAAG,EAAE;QAAE,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,CAAA;IAC3B,MAAM,EAAE,CAAC,CAAA;CACV,CAAA"}

package/esm/endpoint-models/patch-endpoint.d.ts

@@ -1,6 +1,4 @@
-/**
- * Endpoint model for updating entities
- */
+/** PATCH-by-id endpoint contract. `TWritableData` defaults to `Partial<T>`. */
 export type PatchEndpoint<T, TPrimaryKey extends keyof T, TWritableData = Partial<T>> = {
     body: TWritableData;
     url: {

package/esm/endpoint-models/patch-endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patch-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/patch-endpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI;IACtF,IAAI,EAAE,aAAa,CAAA;IACnB,GAAG,EAAE;QAAE,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;CACf,CAAA"}
+{"version":3,"file":"patch-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/patch-endpoint.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI;IACtF,IAAI,EAAE,aAAa,CAAA;IACnB,GAAG,EAAE;QAAE,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;CACf,CAAA"}

package/esm/endpoint-models/post-endpoint.d.ts

@@ -1,7 +1,5 @@
 import type { WithOptionalId } from '@furystack/core';
-/**
- * Endpoint model for creating new entities
- */
+/** POST endpoint contract. `TPostData` defaults to `T` with the primary key optional. */
 export type PostEndpoint<T, TPrimaryKey extends keyof T, TPostData = WithOptionalId<T, TPrimaryKey>> = {
     body: TPostData;
     result: T;

package/esm/endpoint-models/post-endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"post-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/post-endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,EAAE,SAAS,GAAG,cAAc,CAAC,CAAC,EAAE,WAAW,CAAC,IAAI;IACrG,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,CAAC,CAAA;CACV,CAAA"}
+{"version":3,"file":"post-endpoint.d.ts","sourceRoot":"","sources":["../../src/endpoint-models/post-endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,yFAAyF;AACzF,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,EAAE,SAAS,GAAG,cAAc,CAAC,CAAC,EAAE,WAAW,CAAC,IAAI;IACrG,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,CAAC,CAAA;CACV,CAAA"}

package/esm/request-error.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Throw inside a `RequestAction` to short-circuit with a specific HTTP
+ * status. `ErrorAction` translates this to `JsonResult({ message }, responseCode)`.
+ * Prefer this over plain `Error` (`furystack/rest-action-use-request-error`
+ * enforces this).
+ */
 export declare class RequestError extends Error {
     readonly responseCode: number;
     constructor(msg: string, responseCode: number);

package/esm/request-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-error.d.ts","sourceRoot":"","sources":["../src/request-error.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;aAGnB,YAAY,EAAE,MAAM;gBADpC,GAAG,EAAE,MAAM,EACK,YAAY,EAAE,MAAM;CAIvC"}
+{"version":3,"file":"request-error.d.ts","sourceRoot":"","sources":["../src/request-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAGnB,YAAY,EAAE,MAAM;gBADpC,GAAG,EAAE,MAAM,EACK,YAAY,EAAE,MAAM;CAIvC"}

package/esm/request-error.js

@@ -1,3 +1,9 @@
+/**
+ * Throw inside a `RequestAction` to short-circuit with a specific HTTP
+ * status. `ErrorAction` translates this to `JsonResult({ message }, responseCode)`.
+ * Prefer this over plain `Error` (`furystack/rest-action-use-request-error`
+ * enforces this).
+ */
 export class RequestError extends Error {
     responseCode;
     constructor(msg, responseCode) {

package/esm/request-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"request-error.js","sourceRoot":"","sources":["../src/request-error.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAGnB;IAFlB,YACE,GAAW,EACK,YAAoB;QAEpC,KAAK,CAAC,GAAG,CAAC,CAAA;QAFM,iBAAY,GAAZ,YAAY,CAAQ;IAGtC,CAAC;CACF"}
+{"version":3,"file":"request-error.js","sourceRoot":"","sources":["../src/request-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAGnB;IAFlB,YACE,GAAW,EACK,YAAoB;QAEpC,KAAK,CAAC,GAAG,CAAC,CAAA;QAFM,iBAAY,GAAZ,YAAY,CAAQ;IAGtC,CAAC;CACF"}

package/esm/serialize-to-query-string.d.ts

@@ -1,13 +1,19 @@
 /**
- * Serialize steps:
- * 1. Stringify the value (even primitives, ensure type safety), e.g.: { foo: 'bar😉' } => '{"foo":"bar😉"}'
- * 2. Encode as an URI Component, e.g.: ''{"foo":"bar😉"}'' => '%7B%22foo%22%3A%22bar%F0%9F%98%89%22%7D'
- * 3. Unescape the URI Component, e.g.: '%7B%22foo%22%3A%22bar%F0%9F%98%89%22%7D' => '{"foo":"barð\x9F\x98\x89"}' - This and the first encodeURIComponent is needed because btoa only supports ASCII characters. We also don't want to encode the whole JSON string to keep a reasonable string length
- * 4. Encode the string as base64, e.g.: '{"foo":"barð\x9F\x98\x89"}' => 'eyJmb28iOiJiYXLwn5iJIn0='
- * 5. Encode as an URL Param: 'eyJmb28iOiJiYXLwn5iJIn0=' => 'eyJmb28iOiJiYXLwn5iJIn0%3D'
- * @param value The value to encode
- * @returns The encoded value that can be used as an URL search parameter
+ * Serializes any JSON-stringifiable value to a URL-safe base64 string
+ * suitable for `application/x-www-form-urlencoded`. Pipeline:
+ *
+ * 1. `JSON.stringify` (preserves type info even for primitives)
+ * 2. `encodeURIComponent` (UTF-8 → percent-encoded ASCII so `btoa` works)
+ * 3. `unescape` (drop the percent encoding before base64)
+ * 4. `btoa` (base64 — keeps the result short)
+ * 5. `encodeURIComponent` (URL-safe `=` → `%3D`)
+ *
+ * Reversed by `decode` in `deserialize-query-string.ts`.
  */
 export declare const serializeValue: (value: any) => string;
+/**
+ * Encodes an object as a query string. `undefined` values are skipped;
+ * every other value is run through {@link serializeValue}.
+ */
 export declare const serializeToQueryString: <T extends object>(queryObject: T) => string;
 //# sourceMappingURL=serialize-to-query-string.d.ts.map

package/esm/serialize-to-query-string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize-to-query-string.d.ts","sourceRoot":"","sources":["../src/serialize-to-query-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,GAAG,WACsC,CAAA;AAE/E,eAAO,MAAM,sBAAsB,GAAI,CAAC,SAAS,MAAM,EAAE,aAAa,CAAC,KAAG,MAQzE,CAAA"}
+{"version":3,"file":"serialize-to-query-string.d.ts","sourceRoot":"","sources":["../src/serialize-to-query-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,GAAG,WACsC,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,CAAC,SAAS,MAAM,EAAE,aAAa,CAAC,KAAG,MAQzE,CAAA"}

package/esm/serialize-to-query-string.js

@@ -1,14 +1,20 @@
 /**
- * Serialize steps:
- * 1. Stringify the value (even primitives, ensure type safety), e.g.: { foo: 'bar😉' } => '{"foo":"bar😉"}'
- * 2. Encode as an URI Component, e.g.: ''{"foo":"bar😉"}'' => '%7B%22foo%22%3A%22bar%F0%9F%98%89%22%7D'
- * 3. Unescape the URI Component, e.g.: '%7B%22foo%22%3A%22bar%F0%9F%98%89%22%7D' => '{"foo":"barð\x9F\x98\x89"}' - This and the first encodeURIComponent is needed because btoa only supports ASCII characters. We also don't want to encode the whole JSON string to keep a reasonable string length
- * 4. Encode the string as base64, e.g.: '{"foo":"barð\x9F\x98\x89"}' => 'eyJmb28iOiJiYXLwn5iJIn0='
- * 5. Encode as an URL Param: 'eyJmb28iOiJiYXLwn5iJIn0=' => 'eyJmb28iOiJiYXLwn5iJIn0%3D'
- * @param value The value to encode
- * @returns The encoded value that can be used as an URL search parameter
+ * Serializes any JSON-stringifiable value to a URL-safe base64 string
+ * suitable for `application/x-www-form-urlencoded`. Pipeline:
+ *
+ * 1. `JSON.stringify` (preserves type info even for primitives)
+ * 2. `encodeURIComponent` (UTF-8 → percent-encoded ASCII so `btoa` works)
+ * 3. `unescape` (drop the percent encoding before base64)
+ * 4. `btoa` (base64 — keeps the result short)
+ * 5. `encodeURIComponent` (URL-safe `=` → `%3D`)
+ *
+ * Reversed by `decode` in `deserialize-query-string.ts`.
  */
 export const serializeValue = (value) => encodeURIComponent(btoa(unescape(encodeURIComponent(JSON.stringify(value)))));
+/**
+ * Encodes an object as a query string. `undefined` values are skipped;
+ * every other value is run through {@link serializeValue}.
+ */
 export const serializeToQueryString = (queryObject) => {
     return new URLSearchParams(Object.fromEntries(Object.entries(queryObject)
         .filter(([, value]) => value !== undefined)

package/esm/serialize-to-query-string.js.map

@@ -1 +1 @@
-{"version":3,"file":"serialize-to-query-string.js","sourceRoot":"","sources":["../src/serialize-to-query-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAU,EAAE,EAAE,CAC3C,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAE/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAmB,WAAc,EAAU,EAAE;IACjF,OAAO,IAAI,eAAe,CACxB,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;SACxB,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CACvD,CACF,CAAC,QAAQ,EAAE,CAAA;AACd,CAAC,CAAA"}
+{"version":3,"file":"serialize-to-query-string.js","sourceRoot":"","sources":["../src/serialize-to-query-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAU,EAAE,EAAE,CAC3C,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAmB,WAAc,EAAU,EAAE;IACjF,OAAO,IAAI,eAAe,CACxB,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;SACxB,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CACvD,CACF,CAAC,QAAQ,EAAE,CAAA;AACd,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/rest",
-  "version": "10.0.0",
+  "version": "10.0.1",
   "description": "Generic REST package",
   "type": "module",
   "scripts": {
@@ -38,13 +38,13 @@
   },
   "homepage": "https://github.com/furystack/furystack",
   "dependencies": {
-    "@furystack/core": "^17.0.0",
-    "@furystack/inject": "^13.0.0"
+    "@furystack/core": "^17.1.0",
+    "@furystack/inject": "^13.0.1"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.7"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/api-endpoint-schema.ts

@@ -21,49 +21,27 @@ import type { RestApi } from './rest-api.js'
 export type Schema = unknown
 
 /**
- * Represents the definition of an API endpoint, including its path, schema, and schema name.
- * The HTTP method is now implicit in the structure key.
+ * Reflection metadata for a single endpoint. Populated by the wrappers
+ * applied at definition time (`Validate()`, `Authenticate()`) and read by
+ * `generateOpenApiDocument` and the `/schema` action. The HTTP method is
+ * implicit in the parent {@link ApiEndpointSchema} structure key.
  */
 export type ApiEndpointDefinition = {
-  /**
-   * The path of the endpoint, which is the URL pattern that the endpoint responds to.
-   */
   path: string
-  /**
-   * The JSON schema that defines the structure of the request and response for this endpoint.
-   * To include a schema, wrap your endpoint with a Validate({...}) call during the implementation.
-   */
+  /** Populated by `Validate({ schema })`. Empty string when missing. */
   schema: Schema
-  /**
-   * The name of the schema, which can be used to reference this schema in documentation or other contexts.
-   * To include a schema name, wrap your endpoint with a Validate({...}) call during the implementation.
-   */
+  /** Populated by `Validate({ schemaName })`. Empty string when missing. */
   schemaName: string
-  /**
-   * Indicates whether the endpoint requires authentication.
-   * To include the flag, wrap your endpoint with an Authenticate() call during the implementation.
-   */
+  /** Populated by `Authenticate()` wrapping the action. */
   isAuthenticated: boolean
-  /**
-   * Tags for API documentation grouping.
-   */
   tags?: string[]
-  /**
-   * Marks the endpoint as deprecated.
-   */
   deprecated?: boolean
-  /**
-   * A short summary of the endpoint.
-   */
   summary?: string
-  /**
-   * A longer description of the endpoint.
-   */
   description?: string
   /**
-   * The OpenAPI security scheme names required for this endpoint.
-   * When present, used by `generateOpenApiDocument` to emit accurate per-operation `security`.
-   * When absent, falls back to the `isAuthenticated` boolean behavior.
+   * OpenAPI security scheme names required for this endpoint. Populated by
+   * `Authorize()` and friends. When present overrides the
+   * `isAuthenticated` boolean fallback in `generateOpenApiDocument`.
    */
   securitySchemes?: string[]
 }

package/src/deserialize-query-string.ts

@@ -1,10 +1,9 @@
 import { RequestError } from './request-error.js'
 
 /**
- * Decodes a URL-safe base64 encoded JSON string back to its original value
- * Decoding steps: See the encoding steps in reverse order
- * @param value The value to decode
- * @returns The decoded value
+ * Reverses the encoding produced by `serializeValue`. Throws a 400
+ * {@link RequestError} on malformed input — surfaces to clients as a
+ * "bad request" rather than crashing the server.
  */
 export const decode = <T>(value: string): T => {
   try {
@@ -14,10 +13,14 @@ export const decode = <T>(value: string): T => {
   }
 }
 
+/**
+ * Decodes a query string into a typed object. Empty keys/values are
+ * skipped. Each surviving value is deserialized via {@link decode}.
+ */
 export const deserializeQueryString = (fullQueryString: string) => {
   const params = [...new URLSearchParams(fullQueryString).entries()]
     .filter(([key, value]) => key && value)
     .map(([key, value]) => [key, decode(value)] as const)
 
-  return Object.fromEntries(params) as Record<string, unknown>
+  return Object.fromEntries(params)
 }

package/src/endpoint-models/delete-endpoint.ts

@@ -1,6 +1,4 @@
-/**
- * Endpoint model for deleting entities
- */
+/** DELETE-by-id endpoint contract. */
 export type DeleteEndpoint<T, TPrimaryKey extends keyof T> = {
   url: { id: T[TPrimaryKey] }
   result: object

package/src/endpoint-models/get-collection-endpoint.ts

@@ -1,22 +1,15 @@
 import type { FindOptions } from '@furystack/core'
 
 /**
- * Response Model for GetCollection
+ * Collection result. `count` is the **total** matching entity count
+ * (ignores `top` / `skip`); `entries` is the page returned for this query.
  */
 export type GetCollectionResult<T> = {
-  /**
-   * The Total count of entities
-   */
   count: number
-  /**
-   * List of the selected entities
-   */
   entries: T[]
 }
 
-/**
- * Rest endpoint model for getting / querying collections
- */
+/** GET-collection endpoint contract. */
 export type GetCollectionEndpoint<T> = {
   query: { findOptions?: FindOptions<T, Array<keyof T>> }
   result: GetCollectionResult<T>

package/src/endpoint-models/get-endpoint.ts

@@ -1,18 +1,6 @@
-/**
- * Endpoint model for getting a single entity
- */
+/** GET-by-id endpoint contract. `select` narrows the projected fields. */
 export type GetEntityEndpoint<T, TPrimaryKey extends keyof T> = {
-  query: {
-    /**
-     * The list of fields to select
-     */
-    select?: Array<keyof T>
-  }
-  url: {
-    /**
-     * The entity's unique identifier
-     */
-    id: T[TPrimaryKey]
-  }
+  query: { select?: Array<keyof T> }
+  url: { id: T[TPrimaryKey] }
   result: T
 }

package/src/endpoint-models/patch-endpoint.ts

@@ -1,6 +1,4 @@
-/**
- * Endpoint model for updating entities
- */
+/** PATCH-by-id endpoint contract. `TWritableData` defaults to `Partial<T>`. */
 export type PatchEndpoint<T, TPrimaryKey extends keyof T, TWritableData = Partial<T>> = {
   body: TWritableData
   url: { id: T[TPrimaryKey] }

package/src/endpoint-models/post-endpoint.ts

@@ -1,8 +1,6 @@
 import type { WithOptionalId } from '@furystack/core'
 
-/**
- * Endpoint model for creating new entities
- */
+/** POST endpoint contract. `TPostData` defaults to `T` with the primary key optional. */
 export type PostEndpoint<T, TPrimaryKey extends keyof T, TPostData = WithOptionalId<T, TPrimaryKey>> = {
   body: TPostData
   result: T

package/src/request-error.ts

@@ -1,3 +1,9 @@
+/**
+ * Throw inside a `RequestAction` to short-circuit with a specific HTTP
+ * status. `ErrorAction` translates this to `JsonResult({ message }, responseCode)`.
+ * Prefer this over plain `Error` (`furystack/rest-action-use-request-error`
+ * enforces this).
+ */
 export class RequestError extends Error {
   constructor(
     msg: string,

package/src/serialize-to-query-string.ts

@@ -1,16 +1,22 @@
 /**
- * Serialize steps:
- * 1. Stringify the value (even primitives, ensure type safety), e.g.: { foo: 'bar😉' } => '{"foo":"bar😉"}'
- * 2. Encode as an URI Component, e.g.: ''{"foo":"bar😉"}'' => '%7B%22foo%22%3A%22bar%F0%9F%98%89%22%7D'
- * 3. Unescape the URI Component, e.g.: '%7B%22foo%22%3A%22bar%F0%9F%98%89%22%7D' => '{"foo":"barð\x9F\x98\x89"}' - This and the first encodeURIComponent is needed because btoa only supports ASCII characters. We also don't want to encode the whole JSON string to keep a reasonable string length
- * 4. Encode the string as base64, e.g.: '{"foo":"barð\x9F\x98\x89"}' => 'eyJmb28iOiJiYXLwn5iJIn0='
- * 5. Encode as an URL Param: 'eyJmb28iOiJiYXLwn5iJIn0=' => 'eyJmb28iOiJiYXLwn5iJIn0%3D'
- * @param value The value to encode
- * @returns The encoded value that can be used as an URL search parameter
+ * Serializes any JSON-stringifiable value to a URL-safe base64 string
+ * suitable for `application/x-www-form-urlencoded`. Pipeline:
+ *
+ * 1. `JSON.stringify` (preserves type info even for primitives)
+ * 2. `encodeURIComponent` (UTF-8 → percent-encoded ASCII so `btoa` works)
+ * 3. `unescape` (drop the percent encoding before base64)
+ * 4. `btoa` (base64 — keeps the result short)
+ * 5. `encodeURIComponent` (URL-safe `=` → `%3D`)
+ *
+ * Reversed by `decode` in `deserialize-query-string.ts`.
  */
 export const serializeValue = (value: any) =>
   encodeURIComponent(btoa(unescape(encodeURIComponent(JSON.stringify(value)))))
 
+/**
+ * Encodes an object as a query string. `undefined` values are skipped;
+ * every other value is run through {@link serializeValue}.
+ */
 export const serializeToQueryString = <T extends object>(queryObject: T): string => {
   return new URLSearchParams(
     Object.fromEntries(