@sincpro/client-framework 0.4.0 → 0.6.0

package/dist/common/time.js

@@ -57,6 +57,9 @@ const pad = (n) => String(n).padStart(2, "0");
 /** `"2026-03-12T14:30:00Z"` → `"2026-03-12T10:30"` in `America/La_Paz`: the wall clock there,
  *  as a date-and-time control reads it. `null` when it is not an instant. */
 export function wallTimeOf(instant, timeZone) {
+    // A day alone is not an instant: `Date` would read it as midnight in UTC, the day before here.
+    if (!/T\d{2}:\d{2}/.test(instant))
+        return null;
     const at = Date.parse(instant);
     if (Number.isNaN(at))
         return null;
@@ -82,9 +85,13 @@ export function instantOf(wall, timeZone) {
     return new Date(second).toISOString();
 }
 const DAY = /^\d{4}-\d{2}-\d{2}$/;
-/** A day of the calendar as the server writes it: `"2026-03-12"` — never an instant. */
+/** A day of the calendar as the server writes it: `"2026-03-12"` — never an instant, never a day
+ *  the calendar does not have (`"2026-02-30"`, which `Date` would roll into March). */
 export function isDay(text) {
-    return DAY.test(text) && !Number.isNaN(Date.parse(`${text}T00:00:00Z`));
+    if (!DAY.test(text))
+        return false;
+    const at = Date.parse(`${text}T00:00:00Z`);
+    return !Number.isNaN(at) && new Date(at).toISOString().slice(0, 10) === text;
 }
 /** The day it is at `instant` on the wall clock of `timeZone`: what «today» means for a company.
  *  `null` when it is not an instant. */

package/dist/context/codec.d.ts

@@ -13,6 +13,8 @@ import type { ContextValues } from "./store.js";
  * context stays where it is. Reading never fails a context whole: text that is not a JSON object
  * reads as an empty one. A project with a schema of its own writes its own codec over this port.
  */
+/** The header the context travels in: the one sincpro_framework's entrances read. */
+export declare const CONTEXT_HEADER = "sincpro-context";
 export interface ContextCodec {
     dumps(values: ContextValues): string;
     loads(text: string): ContextValues;

package/dist/context/codec.js

@@ -1,3 +1,19 @@
+/**
+ * How a context is written to text and read back: what a `ContextStore` that persists uses
+ * (`sessionStorage`, MMKV), and what travels to the server in `sincpro-context`.
+ *
+ *     plainCodec.dumps({ tenant_id: "acme", company_id: 2, session: socket })
+ *       →  '{"tenant_id":"acme","company_id":2}'
+ *     plainCodec.loads('{"tenant_id":"acme"}')   →  { tenant_id: "acme" }
+ *
+ * Context: sincpro_framework's `ContextCodec`, and its `PlainCodec` — the one for anything outside
+ * the codebase: another language, a browser, a phone. Only the travelling values go — text,
+ * numbers, booleans, `null`, and lists of them; an object, a function or a connection held in the
+ * context stays where it is. Reading never fails a context whole: text that is not a JSON object
+ * reads as an empty one. A project with a schema of its own writes its own codec over this port.
+ */
+/** The header the context travels in: the one sincpro_framework's entrances read. */
+export const CONTEXT_HEADER = "sincpro-context";
 function isPlain(value) {
     return (value === null ||
         typeof value === "string" ||

package/dist/index.d.ts

@@ -7,7 +7,8 @@
  * client it calls and the entity it reads come from the same place.
  *
  *   common/   the values of the wire, as the backend writes them: ids, a day and an instant,
- *             `Decimal`, `Money`, and how any value is written and read (`valuesOf`, `rebuilt`)
+ *             `Decimal`, `Money`, a to-many as a page of its records (`EntityCollection`), and
+ *             how any value is written and read (`valuesOf`, `rebuilt`)
  *   client/   the seam with a server: the transport and its REST and in-memory implementations,
  *             entities with typed commands, the service's client contract
  *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
@@ -20,17 +21,18 @@
  * `@sincpro/client-framework/testing`: neither is part of what an application runs.
  */
 export { type ClientContract, entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
-export { bodyFor, type CommandAnswers, type CommandBodies, type CommandRoute, type Entity, entity, type EntityRef, type EntityRoutes, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, type SummaryFields, type SummaryPart, TRAIL_PARAM, WITH_PARAM, type WriteRoute, writeRoute, } from "./client/entity.js";
+export { bodyFor, type CommandAnswers, type CommandBodies, type CommandRoute, type Entity, entity, type EntityRef, type EntityRoutes, type ExportFormat, exportRoute, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, type SummaryFields, type SummaryPart, TRAIL_PARAM, WITH_PARAM, type WriteRoute, writeRoute, } from "./client/entity.js";
 export { type MemoryOptions, type MemoryTable, memoryTransport, } from "./client/memory.js";
 export { type RestOptions, restTransport, urlOf, type VersionDrift, } from "./client/rest.js";
 export { type RetryKeys, retryKeys, unanswered, } from "./client/retry.js";
-export { type CallOptions, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./client/transport.js";
+export { type CallOptions, type Decoder, type Download, downloadRoute, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./client/transport.js";
+export { collectionOf, type EntityCollection, type HeldCollection, isCollection, isPartial, relatedCriteria, type RelationKeys, totalOf, } from "./common/collection.js";
 export { Decimal, type DecimalLike } from "./common/decimal.js";
 export { isEntityId, momentOf, newEntityId } from "./common/ids.js";
 export { Money } from "./common/money.js";
 export { BYTES, type JsonValue, pack, readValues, type Rebuild, rebuilt, unpack, valuesOf, } from "./common/serialization.js";
 export { dayOf, installTimeZone, instantOf, isDay, timeZoneNow, wallTimeOf, } from "./common/time.js";
-export { type ContextCodec, plainCodec, travelling, travels, } from "./context/codec.js";
+export { CONTEXT_HEADER, type ContextCodec, plainCodec, travelling, travels, } from "./context/codec.js";
 export { type Context } from "./context/context.js";
 export { type ContextStore, type ContextValues, memoryContexts, } from "./context/store.js";
 export { defineMeta, field, type FieldOptions, type MetaSpec, type Words, } from "./model/meta.js";
@@ -41,3 +43,5 @@ export { type BoundedContext, UseBoundedContext, } from "./services/bounded-cont
 export { BIND, type Bindable, bindable, bindDependency, bindTransport, type Execution, headersOf, } from "./services/execution.js";
 export { ApplicationService, Feature, type ServiceClasses, type ServiceMethods, type Services, } from "./services/feature.js";
 export { configureProcess, outcomeOf, processContext, type ProcessOptions, } from "./services/process.js";
+export { reportError } from "./services/report.js";
+export { screensTransport } from "./services/screens.js";

package/dist/index.js

@@ -7,7 +7,8 @@
  * client it calls and the entity it reads come from the same place.
  *
  *   common/   the values of the wire, as the backend writes them: ids, a day and an instant,
- *             `Decimal`, `Money`, and how any value is written and read (`valuesOf`, `rebuilt`)
+ *             `Decimal`, `Money`, a to-many as a page of its records (`EntityCollection`), and
+ *             how any value is written and read (`valuesOf`, `rebuilt`)
  *   client/   the seam with a server: the transport and its REST and in-memory implementations,
  *             entities with typed commands, the service's client contract
  *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
@@ -20,17 +21,18 @@
  * `@sincpro/client-framework/testing`: neither is part of what an application runs.
  */
 export { entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
-export { bodyFor, entity, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./client/entity.js";
+export { bodyFor, entity, exportRoute, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./client/entity.js";
 export { memoryTransport, } from "./client/memory.js";
 export { restTransport, urlOf, } from "./client/rest.js";
 export { retryKeys, unanswered, } from "./client/retry.js";
-export { readRoute, TransportError, } from "./client/transport.js";
+export { downloadRoute, readRoute, TransportError, } from "./client/transport.js";
+export { collectionOf, isCollection, isPartial, relatedCriteria, totalOf, } from "./common/collection.js";
 export { Decimal } from "./common/decimal.js";
 export { isEntityId, momentOf, newEntityId } from "./common/ids.js";
 export { Money } from "./common/money.js";
 export { BYTES, pack, readValues, rebuilt, unpack, valuesOf, } from "./common/serialization.js";
 export { dayOf, installTimeZone, instantOf, isDay, timeZoneNow, wallTimeOf, } from "./common/time.js";
-export { plainCodec, travelling, travels, } from "./context/codec.js";
+export { CONTEXT_HEADER, plainCodec, travelling, travels, } from "./context/codec.js";
 export {} from "./context/context.js";
 export { memoryContexts, } from "./context/store.js";
 export { defineMeta, field, } from "./model/meta.js";
@@ -41,3 +43,5 @@ export { UseBoundedContext, } from "./services/bounded-context.js";
 export { BIND, bindable, bindDependency, bindTransport, headersOf, } from "./services/execution.js";
 export { ApplicationService, Feature, } from "./services/feature.js";
 export { configureProcess, outcomeOf, processContext, } from "./services/process.js";
+export { reportError } from "./services/report.js";
+export { screensTransport } from "./services/screens.js";

package/dist/model/meta.d.ts

@@ -69,6 +69,7 @@ export declare const field: {
         holds?: Expression | null;
         computes?: import("@sincpro/criteria").Formula | null;
         navigable?: boolean;
+        reference?: boolean;
         total?: string | null;
         many?: boolean;
         relation?: string | null;

package/dist/observability/ports.d.ts

@@ -47,7 +47,8 @@ export interface Tracer {
 }
 /** What a report says about where the error happened. */
 export type ErrorAbout = {
-    /** `<bounded context>.<Service>[.<method>]`: the use case's identity, as the backend's. */
+    /** `<bounded context>.<Service>[.<method>]`: the use case's identity, as the backend's — or,
+     *  for what failed outside one (`reportError`), where it happened (`view project:issue/acme-3`). */
     useCase: string;
     /** The trace the error belongs to — the same id the server logged, when it got that far. */
     traceId: string;

package/dist/services/bounded-context.js

@@ -3,10 +3,11 @@ import { contextAt } from "../context/context.js";
 import { bindDependency } from "./execution.js";
 import { composes, isApplicationServiceClass, isFeatureClass, methodsOf, } from "./feature.js";
 import { processContext, processNow, processStore, } from "./process.js";
+import { firstReport } from "./report.js";
 /** Names `project` answers itself: no service is registered under them. */
 const RESERVED = new Set(["name", "context", "with", "scoped"]);
 /** Names a run answers on `this` itself: no dependency is added under them. */
-const ANSWERED = new Set(["context", "feature"]);
+const ANSWERED = new Set(["context", "feature", "span"]);
 export class UseBoundedContext {
     name;
     /** This bounded context's level of the context, saved in the process's store. */
@@ -142,6 +143,8 @@ function viewOf(target, binding, execution) {
         get(held, property, receiver) {
             if (property === "context")
                 return execution.context;
+            if (property === "span")
+                return execution.span;
             if (property === "feature" && isComposer)
                 return (features ??= featuresOf(binding, execution));
             if (typeof property === "string") {
@@ -191,20 +194,6 @@ function contextOf(binding) {
         ...binding.scope,
     };
 }
-/**
- * Whether this is the first run to report this error. A Feature that fails inside an
- * ApplicationService throws through it: the error is reported once, by the run where it
- * happened — its span is the one that says where — and every run around it still ends `failed`.
- */
-const REPORTED = new WeakSet();
-function firstReport(error) {
-    if (error === null || (typeof error !== "object" && typeof error !== "function"))
-        return true;
-    if (REPORTED.has(error))
-        return false;
-    REPORTED.add(error);
-    return true;
-}
 /** What watches a use case never changes what it answers: a tracer or reporter that throws is ignored. */
 function quietly(work, otherwise) {
     try {

package/dist/services/execution.js

@@ -1,4 +1,4 @@
-import { plainCodec, travels } from "../context/codec.js";
+import { CONTEXT_HEADER, plainCodec, travels } from "../context/codec.js";
 /**
  * A dependency that has something to say about the execution it is used in: given that
  * execution, it answers itself bound to it. The transport and every generated client are;
@@ -34,7 +34,7 @@ export function headersOf(execution) {
     }
     // Only what travels: an object or a function held in the context stays in this process.
     if (Object.values(context).some(travels))
-        headers["sincpro-context"] = plainCodec.dumps(context);
+        headers[CONTEXT_HEADER] = plainCodec.dumps(context);
     return headers;
 }
 /**
@@ -58,6 +58,9 @@ export function bindTransport(transport, execution) {
     const read = transport.read;
     if (read !== undefined)
         bound.read = (route, signal, options) => read.call(transport, route, signal, call(options));
+    const download = transport.download;
+    if (download !== undefined)
+        bound.download = (route, signal, options) => download.call(transport, route, signal, call(options));
     return bound;
 }
 /**

package/dist/services/feature.d.ts

@@ -1,4 +1,5 @@
 import type { ContextValues } from "../context/store.js";
+import type { Span } from "../observability/ports.js";
 /**
  * `Feature` and `ApplicationService`: the two kinds of service a bounded context holds, as in
  * sincpro_framework. Each bounded context gives them its dependencies once, in its own base:
@@ -47,6 +48,8 @@ type Within<D extends object, C extends object> = Readonly<D> & {
      * read once where the gesture started and the same for every Feature it runs.
      */
     readonly context: Readonly<Partial<C>>;
+    /** This run's span: a use case says more about what it ran on (`this.span.set({ … })`). */
+    readonly span: Span;
 };
 /** Service classes by the name a bounded context gives them: `{ Issues, Notices }`. */
 export type ServiceClasses = Readonly<Record<string, new () => object>>;
@@ -55,7 +58,7 @@ export type ServiceClasses = Readonly<Record<string, new () => object>>;
  * methods, without its dependencies, its context or its `_` helpers.
  */
 export type ServiceMethods<I, D> = {
-    readonly [M in keyof I as M extends keyof D | "context" | "feature" | `_${string}` ? never : I[M] extends (...args: never[]) => unknown ? M : never]: I[M];
+    readonly [M in keyof I as M extends keyof D | "context" | "feature" | "span" | `_${string}` ? never : I[M] extends (...args: never[]) => unknown ? M : never]: I[M];
 };
 /** The services of a set of classes, by their names. */
 export type Services<S extends ServiceClasses, D> = {

package/dist/services/report.d.ts

@@ -0,0 +1,15 @@
+export declare function firstReport(error: unknown): boolean;
+/**
+ * Reports what nobody expected that is not a use case — a screen that broke while drawing, a
+ * subscriber, a worker — through the process's reporter, with the process's context.
+ *
+ *     <Composer onViewError={(error, { resource }) => reportError(error, `view ${formatRef(resource)}`)} />
+ *     ErrorUtils.setGlobalHandler((error) => reportError(error, "react-native global"));
+ *
+ * Context: a use case reports its own failures (the bounded context does it for it); what fails
+ * outside one would only reach a console. `where` takes the place of the use case's name in the
+ * report. Only what failed is reported (`outcomeOf`: a refusal the server explained or an abort is
+ * not); an error a use case already reported is not reported again; and a reporter that throws is
+ * ignored: telling about a failure never becomes a second one.
+ */
+export declare function reportError(error: unknown, where: string): void;

package/dist/services/report.js

@@ -0,0 +1,53 @@
+import { newEntityId } from "../common/ids.js";
+import { processContext, processNow } from "./process.js";
+/**
+ * Whether this is the first time this error is reported. A Feature that fails inside an
+ * ApplicationService throws through it, and a screen that draws the failure may break on it:
+ * the error is reported once, by the first that saw it — its span is the one that says where.
+ */
+const REPORTED = new WeakSet();
+export function firstReport(error) {
+    if (error === null || (typeof error !== "object" && typeof error !== "function"))
+        return true;
+    if (REPORTED.has(error))
+        return false;
+    REPORTED.add(error);
+    return true;
+}
+/**
+ * Reports what nobody expected that is not a use case — a screen that broke while drawing, a
+ * subscriber, a worker — through the process's reporter, with the process's context.
+ *
+ *     <Composer onViewError={(error, { resource }) => reportError(error, `view ${formatRef(resource)}`)} />
+ *     ErrorUtils.setGlobalHandler((error) => reportError(error, "react-native global"));
+ *
+ * Context: a use case reports its own failures (the bounded context does it for it); what fails
+ * outside one would only reach a console. `where` takes the place of the use case's name in the
+ * report. Only what failed is reported (`outcomeOf`: a refusal the server explained or an abort is
+ * not); an error a use case already reported is not reported again; and a reporter that throws is
+ * ignored: telling about a failure never becomes a second one.
+ */
+export function reportError(error, where) {
+    const settings = processNow();
+    try {
+        // What the server explained, or what the caller stopped waiting for, is not a fault here either.
+        if (settings.outcomeOf(error) !== "failed")
+            return;
+    }
+    catch {
+        // An outcome that cannot be told is a failure.
+    }
+    if (!firstReport(error))
+        return;
+    try {
+        settings.reporter?.report(error, {
+            useCase: where,
+            traceId: "",
+            executionId: newEntityId(),
+            context: processContext.values,
+        });
+    }
+    catch {
+        // Ignored, as a reporter that fails inside a use case is.
+    }
+}

package/dist/services/screens.d.ts

@@ -0,0 +1,2 @@
+import type { Transport } from "../client/transport.js";
+export declare function screensTransport(transport: Transport, name?: string): Transport;

package/dist/services/screens.js

@@ -0,0 +1,76 @@
+import { UseBoundedContext } from "./bounded-context.js";
+import { Feature } from "./feature.js";
+/**
+ * What a screen reads of an entity — a page, a record, a read of its own: sincpro_framework's
+ * built-in `EntityReads`, on the client.
+ */
+class EntityReads extends Feature {
+    list(route, criteria, signal, options) {
+        this.span.set({ "http.route": route });
+        return this.transport.list(route, criteria, signal, options);
+    }
+    one(route, signal, options) {
+        this.span.set({ "http.route": route });
+        return this.transport.one(route, signal, options);
+    }
+    read(route, signal, options) {
+        this.span.set({ "http.route": route });
+        const read = this.transport.read;
+        if (read === undefined)
+            return Promise.reject(new Error(`this transport cannot read ${route}: it has no read()`));
+        return read.call(this.transport, route, signal, options);
+    }
+    download(route, signal, options) {
+        this.span.set({ "http.route": route });
+        const download = this.transport.download;
+        if (download === undefined)
+            return Promise.reject(new Error(`this transport cannot download ${route}: it has no download()`));
+        return download.call(this.transport, route, signal, options);
+    }
+}
+/** What a screen writes — a save, a draft, a preview, a Command: each request a use case. */
+class EntityWrites extends Feature {
+    send(method, route, body, signal, options) {
+        this.span.set({ "http.method": method, "http.route": route });
+        return this.transport.send(method, route, body, signal, options);
+    }
+}
+/**
+ * The transport, every call a use case of a bounded context of its own — `screens` unless named:
+ * what a platform hands the screens it draws.
+ *
+ *     const screens = screensTransport(restTransport({ base: "/v1" }));
+ *     await screens.list("/facturas", criteria);   // span screens/EntityReads.list
+ *
+ * Context: a use case is traced, carries its context and reports what nobody expected; a list a
+ * screen reads through the transport was none of that — no span, no `traceparent` (the backend's
+ * trace started there, with no client in it), no company, and a 500 reported to nobody. Here
+ * each read and write runs as a use case of `screens` — `EntityReads.list`, `.one`, `.read`,
+ * `.download`, `EntityWrites.send` —, so it gets all three the way any other does: the span (its route said
+ * on it), the trace and the process's context on the request, and a report only when it failed
+ * (a 4xx the server explained is the screen's to show). A bounded context's own dependencies are
+ * never given this: there its use case is the one that runs.
+ */
+/** The transports this made: given one again, it is answered as it is — wrapped twice, each
+ *  request would be two unrelated use cases, and the server would see only the outer's trace. */
+const MADE = new WeakSet();
+export function screensTransport(transport, name = "screens") {
+    if (MADE.has(transport))
+        return transport;
+    const screens = new UseBoundedContext(name)
+        .addDependency("transport", transport)
+        .register({ features: { EntityReads, EntityWrites } });
+    const reads = screens.EntityReads;
+    const writes = screens.EntityWrites;
+    const through = {
+        list: (route, criteria, signal, options) => reads.list(route, criteria, signal, options),
+        one: (route, signal, options) => reads.one(route, signal, options),
+        send: (method, route, body, signal, options) => writes.send(method, route, body, signal, options),
+    };
+    if (transport.read !== undefined)
+        through.read = (route, signal, options) => reads.read(route, signal, options);
+    if (transport.download !== undefined)
+        through.download = (route, signal, options) => reads.download(route, signal, options);
+    MADE.add(through);
+    return through;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sincpro/client-framework",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The client side of sincpro_framework, for every platform: Feature and ApplicationService traced and reported by default, applications made of domains, and the typed client generated from a service's contract. No React, no DOM.",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,10 @@
     "./sentry": {
       "types": "./dist/adapters/sentry.d.ts",
       "default": "./dist/adapters/sentry.js"
+    },
+    "./parquet": {
+      "types": "./dist/adapters/parquet.d.ts",
+      "default": "./dist/adapters/parquet.js"
     }
   },
   "bin": {
@@ -68,22 +72,31 @@
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@sincpro/criteria": "^2.0.0"
+    "@sincpro/criteria": "^2.1.0",
+    "hyparquet": "^1.32.0",
+    "typescript": ">=5.5 <7"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
       "optional": true
+    },
+    "hyparquet": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@opentelemetry/api": "1.10.0",
     "@opentelemetry/sdk-trace": "3.1.0",
-    "@sincpro/criteria": "^2.0.0",
+    "@sincpro/criteria": "^2.1.0",
     "@types/node": "^26.6.6",
     "eslint": "^10.14.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-simple-import-sort": "^14.0.0",
+    "hyparquet": "^1.32.0",
     "prettier": "^3.9.10",
     "tsc-alias": "^1.9.9",
     "typescript": "~6.0.3",