@jarenjs/linq 0.72.0 → 0.72.3

package/ARCHITECTURE.md

@@ -49,6 +49,10 @@ document (`{ $count: … }`), and `groupBy` packs its default return as
 `{ key: …, items: [ '$it' ] }` because an object member takes exactly
 one item.
 
+The emitter also owns `requireNonNegativeInteger`, the shared count/index guard
+for synchronous and asynchronous sequence windows and positional terminals.
+Both surfaces report the same `JL0005` refusal at their existing call boundary.
+
 ## The typed surface (`types/index.d.ts`)
 
 Hand-authored declarations are the public type contract (the runtime

package/docs/DB-CLIENT.md

@@ -826,10 +826,10 @@ never builds one; the migration between two of them is
 
 ## 7. Cost
 
-`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->625,827<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->627,769<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.db.kb-->626<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.db.kb-->628<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 It is by far the largest of the ten, and the reason is §1.1's edge rather

package/docs/LINQ-FORMAT.md

@@ -37,7 +37,7 @@ is the index of those guides, and it is how a reader reaches any of them.
 | Document | Lines | What it writes, and when to open it |
 |---|---:|---|
 | [LINQ-FORMAT.md](LINQ-FORMAT.md) | 948 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the documents, or one place to look up a method without knowing which pen owns it |
-| [QUERY-PEN.md](QUERY-PEN.md) | 1,724 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
+| [QUERY-PEN.md](QUERY-PEN.md) | 1,725 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 1,205 | `./schema` — JSON Schema 2020-12: the structural keywords, the constraints and the annotations, each with a method of its own, plus `$query`, `$defs`/`$ref` recursion and the normalizer's per-field predicates. **Read it when** you are describing the shape of data — for validation, for a form, or as the base of an entity |
 | [MODEL-PEN.md](MODEL-PEN.md) | 1,092 | `./model` — the `x-entity` vocabulary on JSON Schema, and the `$model` 0.1 document `openStore` accepts unchanged. **Read it when** you are declaring a store's entities, their keys and their relations |
 | [JSLT-PEN.md](JSLT-PEN.md) | 955 | `./jslt` — `$jslt` 0.1 stylesheets: the envelope and its rules, whose bodies are captured over the matched value. **Read it when** you are transforming one document into another |
@@ -205,7 +205,7 @@ and the bundle is the byte count the tree-shaking probe builds.
 | Document | Subpath | Lines | Mapping rows | Worked examples | Refusals | Bundle |
 |---|---|---:|---:|---:|---:|---:|
 | [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 948 | — | — | — | — |
-| [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,724 | 34 | 8 | 15 | 174,188 B |
+| [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,725 | 34 | 8 | 15 | 174,131 B |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,205 | 82 | 10 | 4 | 36,717 B |
 | [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,092 | 28 | 6 | 3 | 45,143 B |
 | [JSLT-PEN.md](JSLT-PEN.md) | `./jslt` | 955 | 17 | 8 | 3 | 19,856 B |
@@ -219,8 +219,8 @@ and the bundle is the byte count the tree-shaking probe builds.
 | [JTLT-PEN.md](JTLT-PEN.md) | `./jtlt` | 83 | 13 | 1 | 2 | 16,725 B |
 | [PROJECT-PEN.md](PROJECT-PEN.md) | `./project` | 75 | 9 | 1 | 1 | 15,132 B |
 | [CHARTS-PEN.md](CHARTS-PEN.md) | `./charts` | 94 | 21 | 1 | 1 | 17,014 B |
-| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 893 | 41 | 4 | 2 | 625,827 B |
-| **16 documents** | | **12,390** | **371** | **73** | | |
+| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 893 | 41 | 4 | 2 | 627,769 B |
+| **16 documents** | | **12,391** | **371** | **73** | | |
 <!--/fact-->
 
 A pen whose mapping rows are far below its worked examples is a pen
@@ -262,7 +262,7 @@ it and each document publishes it. The rounded column is what
 <!--fact:pens.cost-->
 | Subpath | Document | Bundle | Rounded |
 |---|---|---:|---:|
-| `@jarenjs/linq` | [QUERY-PEN.md](QUERY-PEN.md) | 174,188 B | 174 kB |
+| `@jarenjs/linq` | [QUERY-PEN.md](QUERY-PEN.md) | 174,131 B | 174 kB |
 | `@jarenjs/linq/schema` | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 36,717 B | 37 kB |
 | `@jarenjs/linq/model` | [MODEL-PEN.md](MODEL-PEN.md) | 45,143 B | 45 kB |
 | `@jarenjs/linq/jslt` | [JSLT-PEN.md](JSLT-PEN.md) | 19,856 B | 20 kB |
@@ -276,7 +276,7 @@ it and each document publishes it. The rounded column is what
 | `@jarenjs/linq/jtlt` | [JTLT-PEN.md](JTLT-PEN.md) | 16,725 B | 17 kB |
 | `@jarenjs/linq/project` | [PROJECT-PEN.md](PROJECT-PEN.md) | 15,132 B | 15 kB |
 | `@jarenjs/linq/charts` | [CHARTS-PEN.md](CHARTS-PEN.md) | 17,014 B | 17 kB |
-| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 625,827 B | 626 kB |
+| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 627,769 B | 628 kB |
 <!--/fact-->
 
 Read these as prices, not as scores. `./db` is the largest by an order of

package/docs/QUERY-PEN.md

@@ -728,7 +728,8 @@ const rows = await fromAsync(fed.source('orders'))
 ```
 
 `fed.source(name)` is an ordinary provider source (§8) with the root
-`$.<name>[*]`, and all of a federation's sources share one scope — which
+`$.<name>[*]` (a quoted member selector for names containing punctuation,
+spaces or other characters), and all of a federation's sources share one scope — which
 is exactly what admits the join. The federation is what executes it:
 
 1. each side's own document — the filters and the projection the chain
@@ -1671,14 +1672,14 @@ are shorter:
 ## 17. Cost
 
 A consumer importing `from` from `@jarenjs/linq` and calling one
-terminal bundles **<!--fact:bundle.chain-->174,188<!--/fact--> bytes** (esbuild, ESM, minified, tree-shaken,
+terminal bundles **<!--fact:bundle.chain-->174,131<!--/fact--> bytes** (esbuild, ESM, minified, tree-shaken,
 `platform: 'neutral'`). The figure is measured by
 `scripts/check-tree-shaking.js`'s chain probe and compared with this
 section on every `npm run test:tree-shaking`: it is derived, never typed,
 and a stale one is red here rather than wrong in a document somebody
 reads.
 
-Of that, **<!--fact:bundle.chain.own-->40,258<!--/fact--> bytes** are the chain's own modules — `sequence.js`,
+Of that, **<!--fact:bundle.chain.own-->40,131<!--/fact--> bytes** are the chain's own modules — `sequence.js`,
 `async.js`, `expression.js`, `document.js`, `provider.js`,
 `concurrency.js`, `errors.js` and `schema-of.js`. The remaining ~134 kB
 is the query ENGINE and the core it stands on: a chain's document has to
@@ -1705,7 +1706,7 @@ making:
 `docs/CONSUMING.md` states the rounded price of all ten subpaths in one
 table, each figure held equal to the same measurements. Two of its rows
 are the ones to read together: the chain at <!--fact:bundle.chain.kb-->174<!--/fact--> kB and
-`./db` at <!--fact:bundle.db.kb-->626<!--/fact--> kB.
+`./db` at <!--fact:bundle.db.kb-->628<!--/fact--> kB.
 The client costs what the store costs, by construction, and the chain
 costs what running a query costs.
 
@@ -1714,7 +1715,7 @@ the reason is worth knowing: a bundler counts a shared module once, and
 the chain and every pen share the expression capture (`expression.js`)
 and the coded errors under it (`errors.js`, and `@jarenjs/core`'s error
 and object helpers). A consumer importing the chain AND the schema pen
-bundles **<!--fact:bundle.chain.withSchemaPen-->198,858<!--/fact--> bytes** — **<!--fact:bundle.chain.shared-->12,047<!--/fact--> bytes** less than the sum of the
+bundles **<!--fact:bundle.chain.withSchemaPen-->198,801<!--/fact--> bytes** — **<!--fact:bundle.chain.shared-->12,047<!--/fact--> bytes** less than the sum of the
 figure above and [SCHEMA-PEN.md](SCHEMA-PEN.md#7-cost) §7's, which is
 what those shared modules weigh. The probe measures that pair too, so
 the saving is derived like everything else here. What the chain does NOT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.72.0",
+  "version": "0.72.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -104,13 +104,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.72.0",
-    "@jarenjs/json": "^0.72.0"
+    "@jarenjs/core": "^0.72.3",
+    "@jarenjs/json": "^0.72.3"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.72.0",
-    "@jarenjs/formats": "^0.72.0",
-    "@jarenjs/validate": "^0.72.0"
+    "@jarenjs/db": "^0.72.3",
+    "@jarenjs/formats": "^0.72.3",
+    "@jarenjs/validate": "^0.72.3"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {

package/src/async.js

@@ -45,7 +45,7 @@ import {
 } from './provider.js';
 import {
   emitDocument, wrapTerminal, snapshot, fanProjection, isReservedBinding, RESERVED_BINDINGS_TEXT,
-  PROJECTING_STAGES,
+  PROJECTING_STAGES, requireNonNegativeInteger,
 } from './document.js';
 import { adaptAsyncSource } from './sources.js';
 import { applyMapAsync, normalizeMapAsyncOptions } from './concurrency.js';
@@ -369,8 +369,8 @@ export class AsyncSequence {
     }, params);
   }
 
-  skip(count) { return this.#with({ kind: 'skip', count: requireIndex(count, 'skip') }); }
-  take(count) { return this.#with({ kind: 'take', count: requireIndex(count, 'take') }); }
+  skip(count) { return this.#with({ kind: 'skip', count: requireNonNegativeInteger(count, 'skip') }); }
+  take(count) { return this.#with({ kind: 'take', count: requireNonNegativeInteger(count, 'take') }); }
   distinct() { return this.#with({ kind: 'distinct' }); }
   reverse() { return this.#with({ kind: 'reverse' }); }
 
@@ -722,7 +722,7 @@ export class AsyncSequence {
 
   /** @param {number} index */
   async elementAt(index) {
-    requireIndex(index, 'elementAt');
+    requireNonNegativeInteger(index, 'elementAt');
     const w = this.#pushable()
       ? await this.#pushWindow('elementAt', [index]) : await this.skip(index).#window(1);
     if (w.length === 0) throw new LinqRuntimeError('JL2003', `elementAt(${index}) is out of range`);
@@ -731,7 +731,7 @@ export class AsyncSequence {
 
   /** @param {number} index @param {any} [defaultValue] */
   async elementAtOrDefault(index, defaultValue) {
-    requireIndex(index, 'elementAtOrDefault');
+    requireNonNegativeInteger(index, 'elementAtOrDefault');
     const w = this.#pushable()
       ? await this.#pushWindow('elementAt', [index]) : await this.skip(index).#window(1);
     return w.length === 0 ? defaultValue : w[0];
@@ -832,14 +832,6 @@ async function collect(stream) {
   return out;
 }
 
-/** @param {number} value @param {string} what */
-function requireIndex(value, what) {
-  if (!Number.isInteger(value) || value < 0) {
-    throw new LinqBuildError('JL0005', `${what} takes a non-negative integer, got ${value}`);
-  }
-  return value;
-}
-
 /** @param {any} bindings */
 function validateParams(bindings) {
   if (bindings === null || typeof bindings !== 'object' || Array.isArray(bindings)) {

package/src/db/ledger.js

@@ -132,7 +132,8 @@ export function createDbLedger(client, options = {}) {
     return inside(async (tx) => {
       const c = rows(tx);
       const record = await c.get(r.id);
-      if (record === undefined || record.generation !== r.generation || record.status !== 'started') {
+      if (record === undefined || record.generation !== r.generation || record.status !== 'started'
+        || record.expiresAt <= at) {
         throw stale(ref, 'the key expired, was reclaimed under a newer generation, or was settled already');
       }
       await c.put({ ...record, ...changes, updatedAt: at }, r.id);

package/src/document.js

@@ -39,6 +39,19 @@
 
 import { LinqBuildError } from './errors.js';
 
+/**
+ * Validate a sequence window's count or a positional terminal's index.
+ * @param {number} value
+ * @param {string} what - The operator named by a refusal
+ * @returns {number} The unchanged count or index
+ */
+export function requireNonNegativeInteger(value, what) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new LinqBuildError('JL0005', `${what} takes a non-negative integer, got ${value}`);
+  }
+  return value;
+}
+
 /** The binding names the emitted documents own (QUERY-PEN §7): the
  * item bindings, the accumulator and the group — and the relation-hop
  * bindings `r1`, `r2`, … a capture allocates (expression.js). A

package/src/expression.js

@@ -98,7 +98,7 @@ function bracketName(name) {
  * @param {string} name
  * @returns {string}
  */
-function memberSegment(name) {
+export function memberSegment(name) {
   return SHORTHAND_RE.test(name) ? `.${name}` : bracketName(name);
 }
 

package/src/federate.js

@@ -45,6 +45,7 @@
 
 import { LinqBuildError, LinqRuntimeError } from './errors.js';
 import { compileDocument, isProviderSource, providerRoot } from './provider.js';
+import { memberSegment } from './expression.js';
 
 /** The strategies this boundary knows. One, for now, and it says so. */
 const STRATEGIES = new Set(['hash']);
@@ -123,18 +124,6 @@ function byteSize(row) {
   return encoder.encode(text).length;
 }
 
-/**
- * The root NAME a root expression carries: `'$.Post[*]'` → `'Post'`.
- * A federated source's root is always this shape, because the
- * federation names it.
- * @param {string} root
- * @returns {string}
- */
-function rootName(root) {
-  const match = /^\$\.([^.[\]]+)\[\*\]$/.exec(root);
-  return match === null ? '' : match[1];
-}
-
 /**
  * The FLWOR a terminal wrapped, and how to put a rewritten one back.
  *
@@ -412,7 +401,7 @@ export function federate(spec) {
     // the federated root, which is what the chain binds and what the
     // resident document ranges over; the source's OWN root is what its
     // child document uses, and `childDocument` rewrites between them
-    const root = `$.${name}[*]`;
+    const root = `$${memberSegment(name)}[*]`;
     members.set(root, { name, root, provider, estimatedRows });
   }
 
@@ -448,8 +437,8 @@ export function federate(spec) {
         }, open);
 
       const input = {
-        [rootName(plan.build.root)]: built.rows,
-        [rootName(plan.probe.root)]: probed.rows,
+        [plan.build.member.name]: built.rows,
+        [plan.probe.member.name]: probed.rows,
       };
       const compiled = compileDocument(plan.resident,
         { ...options, externals: options?.externalNames ?? [] });
@@ -462,7 +451,7 @@ export function federate(spec) {
     catch (error) {
       // the call's own failure is the one the caller gets: a cursor
       // that also fails to close must not replace the budget's refusal
-      await closeAll(open);
+      await closeAll(open).catch(() => {});
       throw error;
     }
   };
@@ -513,7 +502,7 @@ export function federate(spec) {
   const handleFor = (name) => {
     let handle = handles.get(name);
     if (handle === undefined) {
-      const root = `$.${name}[*]`;
+      const root = `$${memberSegment(name)}[*]`;
       if (!members.has(root)) {
         throw new LinqBuildError('JL0005',
           `'${name}' is not one of this federation's sources (${names.join(', ')})`);

package/src/sequence.js

@@ -20,7 +20,7 @@ import {
 } from './expression.js';
 import {
   emitDocument, wrapTerminal, snapshot, fanProjection, isReservedBinding, RESERVED_BINDINGS_TEXT,
-  PROJECTING_STAGES,
+  PROJECTING_STAGES, requireNonNegativeInteger,
 } from './document.js';
 import {
   classifySource, compileDocument, executeInMemory, providerRoot, providerRelations, sharesScope,
@@ -31,14 +31,6 @@ import { schemaOf } from './schema-of.js';
 
 const VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
-/** @param {number} value @param {string} what */
-function requireIndex(value, what) {
-  if (!Number.isInteger(value) || value < 0) {
-    throw new LinqBuildError('JL0005', `${what} takes a non-negative integer, got ${value}`);
-  }
-  return value;
-}
-
 /** The immutable query sequence. Construct via `from`/`fromDocument`. */
 export class Sequence {
   #source;
@@ -315,11 +307,11 @@ export class Sequence {
   }
 
   skip(count) {
-    return this.#with({ kind: 'skip', count: requireIndex(count, 'skip') });
+    return this.#with({ kind: 'skip', count: requireNonNegativeInteger(count, 'skip') });
   }
 
   take(count) {
-    return this.#with({ kind: 'take', count: requireIndex(count, 'take') });
+    return this.#with({ kind: 'take', count: requireNonNegativeInteger(count, 'take') });
   }
 
   distinct() {
@@ -557,7 +549,7 @@ export class Sequence {
   }
 
   elementAt(index) {
-    requireIndex(index, 'elementAt');
+    requireNonNegativeInteger(index, 'elementAt');
     const w = this.#window('elementAt', [index]);
     if (w.length === 0) throw new LinqRuntimeError('JL2003', `elementAt(${index}) is out of range`);
     return w[0];
@@ -565,7 +557,7 @@ export class Sequence {
 
   /** @param {number} index @param {any} [defaultValue] */
   elementAtOrDefault(index, defaultValue) {
-    requireIndex(index, 'elementAtOrDefault');
+    requireNonNegativeInteger(index, 'elementAtOrDefault');
     const w = this.#window('elementAt', [index]);
     return w.length === 0 ? defaultValue : w[0];
   }

package/types/charts.d.ts

@@ -75,7 +75,7 @@ export interface ValueSeries {
 /**
  * one boxplot category: raw samples in `values`, or a precomputed five-number summary
  */
-export type Box = unknown & { label: string; values?: Array<number | null>; min?: number; q1?: number; med?: number; q3?: number; max?: number; outliers?: Array<number>; [key: string]: unknown; };
+export type Box = ({ values: unknown; [key: string]: unknown; } | Array<unknown> | string | number | boolean | null | { min: unknown; q1: unknown; med: unknown; q3: unknown; max: unknown; [key: string]: unknown; }) & { label: string; values?: Array<number | null>; min?: number; q1?: number; med?: number; q3?: number; max?: number; outliers?: Array<number>; [key: string]: unknown; };
 
 export interface TreemapItem {
   label: string;
@@ -120,6 +120,16 @@ export interface SankeyLink {
 }
 
 
+/**
+ * Schema constraints this type cannot express: minimum=-180, maximum=180
+ */
+export type MapPointAtItem1 = number;
+
+/**
+ * Schema constraints this type cannot express: minimum=-90, maximum=90
+ */
+export type MapPointAtItem2 = number;
+
 /**
  * a place marker: the convenience path for a caller holding positions rather than GeoJSON
  */
@@ -128,17 +138,37 @@ export interface MapPoint {
    * a GeoJSON position: [longitude, latitude]
    * Schema constraints this type cannot express: minItems=2, maxItems=3
    */
-  at: [number, number, ...Array<number>];
+  at: [MapPointAtItem1, MapPointAtItem2, ...Array<number>];
   label?: string;
   value?: number;
   [key: string]: unknown;
 }
 
 
+export interface SamplingPolicyAnyOf3 {
+  method?: "lttb" | "minmax";
+  /**
+   * the most points one series may draw; an explicit target makes the rendered line independent of any layout
+   * Schema constraints this type cannot express: type="integer", minimum=2
+   */
+  target?: number;
+  /**
+   * the width the derived target assumes, in CSS pixels (default 560)
+   * Schema constraints this type cannot express: exclusiveMinimum=0
+   */
+  width?: number;
+  /**
+   * Schema constraints this type cannot express: exclusiveMinimum=0
+   */
+  pixelRatio?: number;
+  [key: string]: unknown;
+}
+
+
 /**
  * how many of a line's points are drawn: false never samples, a method name or object samples whatever the count, and an omitted member samples a TIME line above 2000 points through @jarenjs/core/series. Distinct from stream.maxPoints, which decides what exists rather than what is drawn.
  */
-export type SamplingPolicy = false | "lttb" | "minmax" | { method?: "lttb" | "minmax"; target?: number; width?: number; pixelRatio?: number; [key: string]: unknown; };
+export type SamplingPolicy = false | "lttb" | "minmax" | SamplingPolicyAnyOf3;
 
 /**
  * the month, weekday and meridiem names a time-axis pattern with a name token reads (compileDateLocale(pack).names from @jarenjs/locales); a name token with no record is a compile error, never an English fallback
@@ -181,11 +211,24 @@ export interface TimeFormats {
 }
 
 
+export interface DomainPolicyX {
+  /**
+   * Schema constraints this type cannot express: exclusiveMinimum=0
+   */
+  window: number;
+  /**
+   * Schema constraints this type cannot express: exclusiveMinimum=0
+   */
+  slide?: number;
+  [key: string]: unknown;
+}
+
+
 /**
  * domain-stability policy: a quantized sliding x window and/or pinned or step-quantized y bounds, so most streaming ticks keep the scales still
  */
 export interface DomainPolicy {
-  x?: { window: number; slide?: number; [key: string]: unknown; };
+  x?: DomainPolicyX;
   y?: "step" | { min?: number; max?: number; [key: string]: unknown; };
   [key: string]: unknown;
 }