@lsmsgpack/client 0.0.0-stage → 2026.10.2901

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @lsmsgpack/client
+
+Reads the `application/x-lsmsgpack` responses of [LsMsgPack's ASP.NET formatters](https://github.com/mlsomers/LsMsgPack/blob/master/docs/WebFormatters.md) into complete JavaScript objects, and writes request bodies they read, in browsers and Node 18+:
+
+- every property of the .NET class is there, also the ones the server left out (`null`, `0`, `false`, `[DefaultValue]`...);
+- polymorphic values get the properties of their actual class, and its name in `$type`;
+- the schema (the property names) is sent once, then the server refers to it;
+- optional generated models ([lsmsgpack-ts](https://github.com/mlsomers/LsMsgPack/blob/master/docs/TypeScriptModels.md)): instances of TypeScript classes with the values the .NET constructors set, typed request bodies, and the server's schemas held before the first request.
+
+No dependencies. Request bodies are sent as plain MsgPack (`application/msgpack`), with `$type` as the type id: polymorphic bodies work too.
+
+```ts
+import { LsMsgPackClient } from '@lsmsgpack/client';
+
+const api = new LsMsgPackClient({ baseUrl: 'https://example.com/' });
+const invoice = await api.get<Invoice>('api/invoices/42');
+await api.post('api/invoices', invoice);
+```
+
+With the generated models and schemas:
+
+```ts
+import { models } from './api/models';
+import { schemas } from './api/models.schemas';
+
+const api = new LsMsgPackClient({ baseUrl: 'https://example.com/', models, schemas });
+```
+
+Documentation: [docs/TypeScriptClient.md](https://github.com/mlsomers/LsMsgPack/blob/master/docs/TypeScriptClient.md) (options, the models, value conversions, polymorphic request bodies, CORS, the described schema).
+
+## Development
+
+```bash
+npm install
+npm test                                # builds, then runs test/*.test.mjs (node:test)
+dotnet build test-server                # enables the tests against the ASP.NET Core formatters (skipped without it)
+dotnet build ../../LsMsgPackTypeScript  # and the ones with models generated by lsmsgpack-ts (test/generated/)
+npm run bench                           # reading and writing 100 invoices: JSON, @msgpack/msgpack, this client with and without models (needs the test server)
+```

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+import { Decoded, Decoder, DecodeOptions } from './decoder.js';
+import { Schema } from './schema.js';
+import { SchemaStore } from './store.js';
+export declare const MediaTypes: {
+    readonly MsgPack: "application/msgpack";
+    readonly XMsgPack: "application/x-msgpack";
+    readonly XLsMsgPack: "application/x-lsmsgpack";
+};
+/** Request header: the ids of the schemas the client holds. */
+export declare const SchemasHeader = "MsgPack-Schemas";
+/** Response header: the id of the schema of the body. */
+export declare const SchemaHeader = "MsgPack-Schema";
+/** The Accept header of the client: the described schema, and application/x-lsmsgpack for servers (and content negotiation) that do not know the parameter. */
+export declare const DescribedAccept: string;
+export interface ClientOptions extends DecodeOptions {
+    /** Relative urls are resolved against it (default: the location of the page, if any). */
+    baseUrl?: string | URL;
+    /** The fetch to use (default: globalThis.fetch). */
+    fetch?: typeof globalThis.fetch;
+    /** Where the schemas are kept, share one between clients of the same servers (default: a new store). */
+    store?: SchemaStore;
+    /** Ask for the described schema, which gives omitted values their defaults and nested objects their properties (default true). */
+    describedSchema?: boolean;
+    /** Tell servers which schemas the client holds, so they refer to them instead of sending them (default true). */
+    negotiateSchemas?: boolean;
+    /** Headers added to every request. */
+    headers?: HeadersInit;
+    /**
+     * The schema set of lsmsgpack-ts (its schemas export): held from the start, so the first response of each type refers to its schema instead of carrying it.
+     * Shared stores: call store.preload once instead.
+     */
+    schemas?: Readonly<Record<string, string | Uint8Array>> | Iterable<string | Uint8Array>;
+}
+/** A request: the options of fetch, with a body that is encoded as MsgPack unless it is already text or bytes. */
+export interface RequestOptions extends Omit<RequestInit, 'body'> {
+    body?: unknown;
+}
+export interface MsgPackResponse<T> {
+    value: T;
+    response: Response;
+    /** The schema of an application/x-lsmsgpack body. */
+    schema?: Schema;
+    /** The body referred to its schema instead of containing it. */
+    reference: boolean;
+}
+export declare class LsMsgPackClient {
+    readonly store: SchemaStore;
+    readonly decoder: Decoder;
+    private readonly fetchFn;
+    private readonly baseUrl?;
+    private readonly described;
+    private readonly negotiate;
+    private readonly headers?;
+    private readonly models?;
+    private readonly generateCode?;
+    constructor(options?: ClientOptions);
+    get<T = unknown>(url: string | URL, init?: RequestOptions): Promise<T>;
+    post<T = unknown>(url: string | URL, body?: unknown, init?: RequestOptions): Promise<T>;
+    put<T = unknown>(url: string | URL, body?: unknown, init?: RequestOptions): Promise<T>;
+    patch<T = unknown>(url: string | URL, body?: unknown, init?: RequestOptions): Promise<T>;
+    delete<T = unknown>(url: string | URL, init?: RequestOptions): Promise<T>;
+    /**
+     * Sends a request and decodes the response. Throws an HttpError for a status outside 200-299 (with the decoded body).
+     * A GET or HEAD whose response refers to a schema the store no longer holds is repeated once without advertising schemas.
+     */
+    send<T = unknown>(url: string | URL, init?: RequestOptions): Promise<MsgPackResponse<T>>;
+    /** Decodes a response (e.g. of your own fetch): MsgPack by its Content-Type, JSON, otherwise text. Learns the schema of an application/x-lsmsgpack body. */
+    read<T = unknown>(response: Response, origin?: string): Promise<MsgPackResponse<T>>;
+    /**
+     * Decodes an application/x-lsmsgpack body.
+     * @param origin the server (scheme://host:port), to learn its schema
+     * @param schemaHeader the response header MsgPack-Schema: an inline schema is kept only when its hash is this id
+     */
+    decode(bytes: Uint8Array, origin?: string, schemaHeader?: string | null): Decoded;
+    private resolve;
+}

package/dist/client.js

@@ -0,0 +1,150 @@
+// A fetch wrapper for the ASP.NET formatters of LsMsgPack: asks for application/x-lsmsgpack with the described schema, tells the server which schemas it holds,
+// learns the schemas of the responses and decodes the bodies into complete objects. Request bodies are sent as plain MsgPack (application/msgpack).
+import { Decoder } from './decoder.js';
+import { HttpError, MissingSchemaError } from './errors.js';
+import { Schema } from './schema.js';
+import { SchemaStore } from './store.js';
+import { encode } from './writer.js';
+export const MediaTypes = {
+    MsgPack: 'application/msgpack',
+    XMsgPack: 'application/x-msgpack',
+    XLsMsgPack: 'application/x-lsmsgpack',
+};
+/** Request header: the ids of the schemas the client holds. */
+export const SchemasHeader = 'MsgPack-Schemas';
+/** Response header: the id of the schema of the body. */
+export const SchemaHeader = 'MsgPack-Schema';
+/** The Accept header of the client: the described schema, and application/x-lsmsgpack for servers (and content negotiation) that do not know the parameter. */
+export const DescribedAccept = `${MediaTypes.XLsMsgPack}; schema=described, ${MediaTypes.XLsMsgPack}; q=0.9`;
+export class LsMsgPackClient {
+    constructor(options = {}) {
+        this.store = options.store ?? new SchemaStore();
+        this.decoder = new Decoder(options);
+        this.models = options.models;
+        this.generateCode = options.generateCode;
+        if (options.schemas !== undefined)
+            this.store.preload(options.schemas);
+        this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.baseUrl = options.baseUrl;
+        this.described = options.describedSchema ?? true;
+        this.negotiate = options.negotiateSchemas ?? true;
+        this.headers = options.headers;
+    }
+    async get(url, init) {
+        return (await this.send(url, { ...init, method: 'GET' })).value;
+    }
+    async post(url, body, init) {
+        return (await this.send(url, { ...init, method: 'POST', body })).value;
+    }
+    async put(url, body, init) {
+        return (await this.send(url, { ...init, method: 'PUT', body })).value;
+    }
+    async patch(url, body, init) {
+        return (await this.send(url, { ...init, method: 'PATCH', body })).value;
+    }
+    async delete(url, init) {
+        return (await this.send(url, { ...init, method: 'DELETE' })).value;
+    }
+    /**
+     * Sends a request and decodes the response. Throws an HttpError for a status outside 200-299 (with the decoded body).
+     * A GET or HEAD whose response refers to a schema the store no longer holds is repeated once without advertising schemas.
+     */
+    async send(url, init = {}) {
+        const target = this.resolve(url);
+        const headers = new Headers(this.headers);
+        new Headers(init.headers).forEach((value, name) => headers.set(name, value));
+        if (!headers.has('Accept'))
+            headers.set('Accept', this.described ? DescribedAccept : MediaTypes.XLsMsgPack);
+        const advertised = this.negotiate && !headers.has(SchemasHeader) ? this.store.advertise(target.origin) : undefined;
+        if (advertised !== undefined)
+            headers.set(SchemasHeader, advertised);
+        let body;
+        if (init.body === undefined || init.body === null || isBodyInit(init.body))
+            body = init.body;
+        else {
+            body = encode(init.body, { models: this.models, generateCode: this.generateCode });
+            if (!headers.has('Content-Type'))
+                headers.set('Content-Type', MediaTypes.MsgPack);
+        }
+        const request = { ...init, headers, body };
+        let result;
+        try {
+            result = await this.read(await this.fetchFn(target, request), target.origin);
+        }
+        catch (e) {
+            const method = (init.method ?? 'GET').toUpperCase();
+            if (!(e instanceof MissingSchemaError) || advertised === undefined || (method !== 'GET' && method !== 'HEAD'))
+                throw e;
+            headers.delete(SchemasHeader); // repeating a GET is safe: the server sends the schema inline
+            result = await this.read(await this.fetchFn(target, request), target.origin);
+        }
+        if (!result.response.ok)
+            throw new HttpError(result.response.status, result.response.statusText, result.value, result.response);
+        return result;
+    }
+    /** Decodes a response (e.g. of your own fetch): MsgPack by its Content-Type, JSON, otherwise text. Learns the schema of an application/x-lsmsgpack body. */
+    async read(response, origin) {
+        const mediaType = (response.headers.get('Content-Type') ?? '').split(';')[0].trim().toLowerCase();
+        if (mediaType === MediaTypes.XLsMsgPack) {
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            const decoded = this.decode(bytes, origin ?? originOf(response.url), response.headers.get(SchemaHeader));
+            return { value: decoded.value, response, schema: decoded.schema, reference: decoded.reference };
+        }
+        if (mediaType === MediaTypes.MsgPack || mediaType === MediaTypes.XMsgPack) {
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            return { value: this.decoder.decodePlain(bytes), response, reference: false };
+        }
+        const text = await response.text();
+        let value = text.length === 0 ? undefined : text; // e.g. 204 No Content for null
+        if (/[/+]json$/.test(mediaType) && text.length > 0)
+            value = JSON.parse(text);
+        return { value: value, response, reference: false };
+    }
+    /**
+     * Decodes an application/x-lsmsgpack body.
+     * @param origin the server (scheme://host:port), to learn its schema
+     * @param schemaHeader the response header MsgPack-Schema: an inline schema is kept only when its hash is this id
+     */
+    decode(bytes, origin, schemaHeader) {
+        const id = schemaHeader?.trim().toLowerCase();
+        const decoded = this.decoder.decode(bytes, (ref) => this.store.get(ref), (schemaBytes) => {
+            const known = id ? this.store.get(id) : undefined;
+            return known !== undefined && sameBytes(known.bytes, schemaBytes) ? known : new Schema(schemaBytes); // parsed once per schema while it is sent inline
+        });
+        if (this.negotiate && origin && decoded.schema !== undefined) {
+            if (decoded.reference)
+                this.store.touch(origin, decoded.schema.id);
+            else
+                this.store.learn(origin, id, decoded.schema);
+        }
+        return decoded;
+    }
+    resolve(url) {
+        const base = this.baseUrl ?? globalThis.location?.href;
+        return base === undefined ? new URL(url) : new URL(url, base);
+    }
+}
+function originOf(url) {
+    try {
+        return url ? new URL(url).origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isBodyInit(body) {
+    return typeof body === 'string' || body instanceof Uint8Array || body instanceof ArrayBuffer || ArrayBuffer.isView(body)
+        || (typeof Blob !== 'undefined' && body instanceof Blob)
+        || (typeof FormData !== 'undefined' && body instanceof FormData)
+        || (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams)
+        || (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream);
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let t = 0; t < a.length; t++)
+        if (a[t] !== b[t])
+            return false;
+    return true;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,gKAAgK;AAChK,oJAAoJ;AAEpJ,OAAO,EAAW,OAAO,EAAiB,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,qBAAqB;IAC9B,QAAQ,EAAE,uBAAuB;IACjC,UAAU,EAAE,yBAAyB;CAC7B,CAAC;AAEX,+DAA+D;AAC/D,MAAM,CAAC,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAC/C,yDAAyD;AACzD,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE7C,+JAA+J;AAC/J,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,UAAU,CAAC,UAAU,uBAAuB,UAAU,CAAC,UAAU,SAAS,CAAC;AAoC7G,MAAM,OAAO,eAAe;IAW1B,YAAY,UAAyB,EAAE;QACrC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,WAAW,EAAE,CAAC;QAChD,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC;QACjD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC;QAClD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,GAAG,CAAc,GAAiB,EAAE,IAAqB;QAC7D,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAI,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,IAAI,CAAc,GAAiB,EAAE,IAAc,EAAE,IAAqB;QAC9E,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAI,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,GAAG,CAAc,GAAiB,EAAE,IAAc,EAAE,IAAqB;QAC7E,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAI,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC3E,CAAC;IAED,KAAK,CAAC,KAAK,CAAc,GAAiB,EAAE,IAAc,EAAE,IAAqB;QAC/E,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAI,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7E,CAAC;IAED,KAAK,CAAC,MAAM,CAAc,GAAiB,EAAE,IAAqB;QAChE,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAI,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IACxE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAc,GAAiB,EAAE,OAAuB,EAAE;QAClE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC5G,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACnH,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QAErE,IAAI,IAAiC,CAAC;QACtC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,IAAI,GAAG,IAAI,CAAC,IAAmC,CAAC;aACvH,CAAC;YACJ,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAwB,CAAC;YAC1G,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;QACpF,CAAC;QAED,MAAM,OAAO,GAAG,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3C,IAAI,MAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAI,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAClF,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACpD,IAAI,CAAC,CAAC,CAAC,YAAY,kBAAkB,CAAC,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,CAAC;gBAAE,MAAM,CAAC,CAAC;YACvH,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,8DAA8D;YAC7F,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAI,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChI,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,4JAA4J;IAC5J,KAAK,CAAC,IAAI,CAAc,QAAkB,EAAE,MAAe;QACzD,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAClG,IAAI,SAAS,KAAK,UAAU,CAAC,UAAU,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;YAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;YACzG,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;QACvG,CAAC;QACD,IAAI,SAAS,KAAK,UAAU,CAAC,OAAO,IAAI,SAAS,KAAK,UAAU,CAAC,QAAQ,EAAE,CAAC;YAC1E,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;YAC3D,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QACrF,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,KAAK,GAAY,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,+BAA+B;QAC1F,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7E,OAAO,EAAE,KAAK,EAAE,KAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAiB,EAAE,MAAe,EAAE,YAA4B;QACrE,MAAM,EAAE,GAAG,YAAY,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE;YACvF,MAAM,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAClD,OAAO,KAAK,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,iDAAiD;QACxJ,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,SAAS,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC7D,IAAI,OAAO,CAAC,SAAS;gBAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;;gBAC9D,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,OAAO,CAAC,GAAiB;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAK,UAA8C,CAAC,QAAQ,EAAE,IAAI,CAAC;QAC5F,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAChE,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,IAAa;IAC/B,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,YAAY,UAAU,IAAI,IAAI,YAAY,WAAW,IAAI,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC;WACnH,CAAC,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,YAAY,IAAI,CAAC;WACrD,CAAC,OAAO,QAAQ,KAAK,WAAW,IAAI,IAAI,YAAY,QAAQ,CAAC;WAC7D,CAAC,OAAO,eAAe,KAAK,WAAW,IAAI,IAAI,YAAY,eAAe,CAAC;WAC3E,CAAC,OAAO,cAAc,KAAK,WAAW,IAAI,IAAI,YAAY,cAAc,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,SAAS,CAAC,CAAa,EAAE,CAAa;IAC7C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACnE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/decoder.d.ts

@@ -0,0 +1,180 @@
+import { MsgPackReader, ReaderOptions } from './reader.js';
+import type { ModelSet } from './models.js';
+import { PropertyNames } from './names.js';
+import { Kind, Schema, SchemaEntry, TypeExpr } from './schema.js';
+import { DecimalMode } from './values.js';
+export interface DecodeOptions extends ReaderOptions {
+    /** long and ulong properties: 'number' (default, as JSON.parse: precision is lost beyond 2^53) or 'bigint' (always a bigint). Untyped values are a bigint only beyond 2^53. */
+    int64?: 'number' | 'bigint';
+    /** DateTime and DateTimeOffset properties: 'date' (default, a Date) or 'iso' (text: DateTime in UTC, DateTimeOffset with its offset). Untyped values are always a Date. */
+    dates?: 'date' | 'iso';
+    /**
+     * The generated models (lsmsgpack-ts, defineModels): an entry of their type name is read into a new instance of its class (its fields have the values the .NET constructor sets,
+     * which a value the data left out keeps), the declared types of its properties are used when the schema has only names. The schema of the payload still decides which property a value is.
+     */
+    models?: ModelSet;
+    /** Classes to create for schema entries (by the type name of the writer), e.g. { Invoice: Invoice }. A property the class does not initialize gets the default. The models come first. */
+    classes?: Record<string, new () => object>;
+    /**
+     * The names of the properties of the objects: 'camelCase' (default, invoiceDate, as System.Text.Json's JsonNamingPolicy.CamelCase names them, the JSON of ASP.NET Core;
+     * also key and value of a KeyValuePair) or 'dotnet' (the names of the .NET properties: InvoiceDate, the default of version 2026.10.22). Never dictionary keys or $type.
+     * The models give theirs (the names of their fields) when it is left out.
+     */
+    propertyNames?: PropertyNames;
+    /** The data starts with the indexed schema (default true, as the formatters write application/x-lsmsgpack). False: the body only (UseInexedSchema off). */
+    indexedSchema?: boolean;
+    /**
+     * Generate the code that creates and fills the objects of each schema entry (new Function, the property names as string literals), default true: about a third faster,
+     * V8 then sees one object shape per place in the code. Without it (or when a Content-Security-Policy does not allow it) a generic loop does the same.
+     */
+    generateCode?: boolean;
+}
+type Fill = (r: SchemaReader, o: Record<string, unknown>, n: number) => void;
+/** The property that holds the type name of an object read with a type id, and that the encoder writes as the type id. */
+export declare const TypeProperty = "$type";
+/** Reads an object of the array layout (the header of n values is read) and returns it complete. */
+type ReadArray = (r: SchemaReader, n: number) => Record<string, unknown>;
+/** Sets a property, also one named __proto__ (as JSON.parse does: an own property, not the prototype). */
+export declare function setOwn(o: Record<string, unknown>, name: string, value: unknown): void;
+type Read = (r: SchemaReader) => unknown;
+interface Default {
+    value: unknown;
+    /** For values that must not be shared (Date, objects). */
+    make?: () => unknown;
+}
+/** How to read the values of one schema entry. */
+declare class Plan {
+    readonly entry: SchemaEntry;
+    readonly cls: (new () => object) | undefined;
+    readonly model: boolean;
+    readonly names: string[];
+    readonly reads: Read[];
+    readonly values: unknown[];
+    readonly makers: ((() => unknown) | undefined)[];
+    /** The properties whose default is made per object (Date, objects): null until the values are read, then made where the data had none (see complete). */
+    made?: number[];
+    readonly isObject: boolean;
+    content?: Read;
+    private _byName?;
+    private createFn?;
+    private createTypedFn?;
+    fillFn?: Fill;
+    /** An object with the defaults, copied by create without generated code (a spread copies an object of the same shape faster than setting each property). */
+    private template?;
+    /** Makes what create and fill use, once the properties are known: the template, and with generateCode their code. */
+    prepare(generateCode: boolean): void;
+    /** readArrayFn for plain objects and the models (not for DecodeOptions.classes: their constructors may do more than set fields). */
+    private generateReadArray;
+    /** The value of a nil in the array layout: what the writer left out (the default of the schema or of the type), not what a class sets. */
+    nilValue(t: number): unknown;
+    /** Reads an object of the array layout into a new object (see generateReadArray), undefined without generated code. */
+    readArrayFn?: ReadArray;
+    /** The properties the class does not initialize (they get the defaults of the schema: e.g. a property the server has and the models do not have yet). */
+    readonly missing: number[];
+    /**
+     * @param names the names of the properties in JavaScript (DecodeOptions.propertyNames)
+     * @param cls the class of the entry (a model, or one of DecodeOptions.classes)
+     * @param model the class is a model: it has $type on its prototype
+     */
+    constructor(entry: SchemaEntry, names: string[], cls: (new () => object) | undefined, model?: boolean);
+    /** A new object with every property at its default (null for the ones that are made, see complete), in the order of the schema. */
+    create(): Record<string, unknown>;
+    /** create for an object that came with a type id: with its type name in $type (the first property; on instances of your classes after their own). */
+    createTyped(): Record<string, unknown>;
+    /** Makes the defaults the data did not replace (a Date or struct is never null, so null means not read). */
+    complete(o: Record<string, unknown>): Record<string, unknown>;
+    /** A new object with every default made (e.g. the default of a struct). */
+    createComplete(): Record<string, unknown>;
+    indexOf(name: string): number;
+    private _byWriterName?;
+    /** The index of a property by the name the writer gave it (a key of ObjectLayout.Map without the schema): the .NET name. */
+    indexOfWriterName(name: string): number;
+}
+/** The plans of one schema for one set of options, made when first used. */
+declare class Plans {
+    readonly schema: Schema;
+    private readonly options;
+    private readonly plans;
+    private readonly inline;
+    readonly root: Read;
+    private readonly field;
+    private readonly keyName;
+    private readonly valueName;
+    constructor(schema: Schema, options: ResolvedOptions);
+    plan(index: number): Plan;
+    /** The plan of an entry by index, or of a struct described inline. */
+    planOf(entry: number | SchemaEntry): Plan;
+    private build;
+    /** A read function for values of the type (each handles nil and values wrapped with a type id). */
+    compile(type: TypeExpr): Read;
+    /** The kinds the formatters write most have their usual format read in place, without the dispatch of value(). */
+    private kind;
+    /** Converts a value of the kind as it was read (undefined: no conversion). Values in another form are returned as they are. */
+    converter(kind: Kind): ((value: unknown) => unknown) | undefined;
+    /** The value of a property the writer left out: the default of its type. */
+    defaultOf(type: TypeExpr): Default;
+    /** A [DefaultValue] of the schema (as read: decimals raw), converted as the values of the property are. */
+    private convertDefault;
+}
+interface ResolvedOptions {
+    decimal: DecimalMode;
+    int64: 'number' | 'bigint';
+    dates: 'date' | 'iso';
+    models?: ModelSet;
+    classes?: Record<string, new () => object>;
+    propertyNames: PropertyNames;
+    generateCode: boolean;
+}
+/** The reader of a body: values wrapped with a type id ({ "": index, "@": content }, or { "": index, 0: value, ... }) become what their schema entry describes. */
+export declare class SchemaReader extends MsgPackReader {
+    private readonly plans;
+    constructor(bytes: Uint8Array, options: ReaderOptions, plans: Plans | null, pos: number);
+    /** The first key of the map whose header was just read is "" (a type id). */
+    private firstKeyIsTypeId;
+    protected map(n: number): unknown;
+    /** A value wrapped with a type id, the header (n entries) is read. */
+    private wrapped;
+    /** An object of the plan: an array of its values (the array layout), a map from property index to value, or a value with a type id. */
+    readObject(plan: Plan): unknown;
+    /**
+     * Values by position, values beyond the entry are skipped. A nil is the value the writer left out (Plan.nilValue: the object made with the defaults has it, an instance of a class gets it),
+     * a value missing after the end of the array keeps what create made (for a class: what its constructor sets).
+     */
+    private fill;
+    /** ObjectLayout.Map: the key is the index of the property in the entry (or its name). */
+    private setByKey;
+    readList(element: Read): unknown;
+    readDictionary(key: Read, value: Read): unknown;
+    /** An array of items of the given types (pairs, tuples), extra items as they are. */
+    readItems(items: Read[]): unknown;
+    /** A DateTime: the timestamps of 4 and 8 bytes read in place. */
+    readDate(): unknown;
+    readRoot(): unknown;
+}
+/** What decoding a payload found. */
+export interface Decoded {
+    value: unknown;
+    /** The schema of the payload (inline or referred to), undefined without one. */
+    schema?: Schema;
+    /** The body referred to its schema instead of containing it. */
+    reference: boolean;
+}
+/** Decodes payloads with the given options (one per client). Thread-safe in the sense of JavaScript: no state between calls except the plans per schema. */
+export declare class Decoder {
+    private readonly options;
+    private readonly readerOptions;
+    private readonly indexedSchema;
+    private readonly plans;
+    constructor(options?: DecodeOptions);
+    /**
+     * Decodes application/x-lsmsgpack data: the schema (or a reference to it) followed by the body.
+     * @param lookup finds a schema the data refers to by its id
+     * @param inline makes the schema of the inline bytes (e.g. the known instance when the bytes are the same), default: parses them
+     */
+    decode(bytes: Uint8Array, lookup?: (id: string) => Schema | undefined, inline?: (schemaBytes: Uint8Array) => Schema): Decoded;
+    /** Plain MsgPack (application/msgpack): any value, maps as objects. */
+    decodePlain(bytes: Uint8Array): unknown;
+    private read;
+    private plansOf;
+}
+export {};