@kanzo-tech/mosaic 0.6.0 → 0.8.0

package/README.md

@@ -15,10 +15,19 @@ Mosaic are two coordinators, and two coordinators are two crossfilters that neve
 ```ts
 import { Coordinator, Selection, MosaicClient, clausePoints } from "@kanzo-tech/mosaic";
 import { column, fillColumn, numbers, IdSetClient } from "@kanzo-tech/mosaic";
+import { engine } from "@kanzo-tech/mosaic";
 ```
 
-- **Re-exports** of the coordinator, the clients, the five clause builders, the loaders and the
-  connector — so a consumer boots a coordinator without a direct `@uwdata` import.
+- **`engine()`** — the page's one DuckDB-WASM database: `{ coordinator, query, lend, hold, drop }`,
+  one per document however many callers ask. vgplot has one active coordinator, so a second boot is
+  a second database the last-mounted chart wins. `lend({ name: url })` registers a URL under a name:
+  the same URL is a no-op, a different one drops the old lease and registers the new, which is what
+  DuckDB-WASM's `File already registered` was refusing. `hold(name, bytes)` registers a copy of a
+  buffer; `drop(names)` forgets. It is fossil's `Engine` structurally, without depending on fossil.
+
+- **Re-exports** of the coordinator, the clients, the five clause builders and the loaders — so a
+  consumer never needs a direct `@uwdata` import. The DuckDB-WASM connector is not among them:
+  `engine()` is the only boot.
 - **`column` / `fillColumn` / `numbers`** — the half of the client protocol the protocol does not
   give you. The coordinator answers with an Arrow table, and Arrow offers a typed column only when
   the type allows one: an integer id gives an array, a dictionary-encoded label gives nothing

package/dist/engine.d.ts

@@ -0,0 +1,34 @@
+import { Coordinator } from '@uwdata/mosaic-core';
+/**
+ * The page's one database: a DuckDB-WASM instance, the Mosaic `Coordinator` over it, and the file
+ * registry, owned in one place.
+ *
+ * **One per document, because vgplot has one.** `MosaicProvider` registers its coordinator as
+ * vgplot's process-wide active one, so a second coordinator on the page is a second database the
+ * last-mounted chart wins. Every host wrote the same memoised boot to avoid it — three in these
+ * docs, one in keasy, one in fossil's playground — and none of them owned the registry beside it.
+ *
+ * **The registry is the part that was missing.** DuckDB-WASM refuses to register a name a second
+ * time under a different URL (`File already registered`), and answers only when the URL is
+ * identical. A signed URL is different on every signing, so the second visit to the same data threw.
+ * `lend` is the one place that knows what is behind a name: the same URL is a no-op, a new one drops
+ * the old lease and registers the new. That indirection is also why the registry is kept rather than
+ * reading `https://…` directly — a view names a stable file, and only the lease behind it rotates.
+ *
+ * It satisfies fossil's `Engine` structurally; this package does not depend on fossil, and does not
+ * name `@duckdb/duckdb-wasm` either — the connector hands the database over untyped.
+ */
+export interface Engine {
+    readonly coordinator: Coordinator;
+    /** Rows as objects, uncached: a read after a `lend` must see the new lease. */
+    query(sql: string): Promise<Record<string, unknown>[]>;
+    /** name → URL. The same URL is a no-op; a different one replaces the lease. */
+    lend(files: Record<string, string>): Promise<void>;
+    /** Registers a copy of `bytes` under `name`, replacing whatever was there. */
+    hold(name: string, bytes: Uint8Array): Promise<void>;
+    /** Unregisters the names. A name the engine does not hold is not an error. */
+    drop(names: readonly string[]): Promise<void>;
+}
+/** The page's one engine, booted on first ask. */
+export declare function engine(): Promise<Engine>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,+EAA+E;IAC/E,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACvD,+EAA+E;IAC/E,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,8EAA8E;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,8EAA8E;IAC9E,IAAI,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAwED,kDAAkD;AAClD,wBAAgB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAIxC"}

package/dist/engine.js

@@ -0,0 +1,38 @@
+import { wasmConnector as u, Coordinator as d } from "@uwdata/mosaic-core";
+const h = 4, w = Symbol("held");
+async function y() {
+  const n = u(), r = new d(n), c = await n.getDuckDB();
+  await r.exec("SET enable_http_metadata_cache = true");
+  const o = /* @__PURE__ */ new Map();
+  let f = Promise.resolve();
+  const s = (e) => {
+    const t = f.then(e);
+    return f = t.catch(() => {
+    }), t;
+  }, i = async (e) => {
+    o.has(e) && (await c.dropFile(e), o.delete(e));
+  };
+  return {
+    coordinator: r,
+    query: (e) => r.query(e, { type: "json", cache: !1 }),
+    lend: (e) => s(async () => {
+      for (const [t, l] of Object.entries(e))
+        o.get(t) !== l && (await i(t), await c.registerFileURL(t, l, h, !1), o.set(t, l));
+    }),
+    hold: (e, t) => s(async () => {
+      await i(e), await c.registerFileBuffer(e, t.slice()), o.set(e, w);
+    }),
+    drop: (e) => s(async () => {
+      for (const t of e) await i(t);
+    })
+  };
+}
+const a = Symbol.for("@kanzo-tech/mosaic/engine");
+function g() {
+  const n = globalThis;
+  return n[a] ?? (n[a] = y()), n[a];
+}
+export {
+  g as engine
+};
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sources":["../src/engine.ts"],"sourcesContent":["import { Coordinator, wasmConnector } from \"@uwdata/mosaic-core\";\n\n/**\n * The page's one database: a DuckDB-WASM instance, the Mosaic `Coordinator` over it, and the file\n * registry, owned in one place.\n *\n * **One per document, because vgplot has one.** `MosaicProvider` registers its coordinator as\n * vgplot's process-wide active one, so a second coordinator on the page is a second database the\n * last-mounted chart wins. Every host wrote the same memoised boot to avoid it — three in these\n * docs, one in keasy, one in fossil's playground — and none of them owned the registry beside it.\n *\n * **The registry is the part that was missing.** DuckDB-WASM refuses to register a name a second\n * time under a different URL (`File already registered`), and answers only when the URL is\n * identical. A signed URL is different on every signing, so the second visit to the same data threw.\n * `lend` is the one place that knows what is behind a name: the same URL is a no-op, a new one drops\n * the old lease and registers the new. That indirection is also why the registry is kept rather than\n * reading `https://…` directly — a view names a stable file, and only the lease behind it rotates.\n *\n * It satisfies fossil's `Engine` structurally; this package does not depend on fossil, and does not\n * name `@duckdb/duckdb-wasm` either — the connector hands the database over untyped.\n */\nexport interface Engine {\n  readonly coordinator: Coordinator;\n  /** Rows as objects, uncached: a read after a `lend` must see the new lease. */\n  query(sql: string): Promise<Record<string, unknown>[]>;\n  /** name → URL. The same URL is a no-op; a different one replaces the lease. */\n  lend(files: Record<string, string>): Promise<void>;\n  /** Registers a copy of `bytes` under `name`, replacing whatever was there. */\n  hold(name: string, bytes: Uint8Array): Promise<void>;\n  /** Unregisters the names. A name the engine does not hold is not an error. */\n  drop(names: readonly string[]): Promise<void>;\n}\n\n/** The slice of DuckDB-WASM's `AsyncDuckDB` the registry uses. */\ninterface Registry {\n  registerFileURL(name: string, url: string, protocol: number, directIO: boolean): Promise<void>;\n  registerFileBuffer(name: string, buffer: Uint8Array): Promise<void>;\n  dropFile(name: string): Promise<void>;\n}\n\n/** `DuckDBDataProtocol.HTTP` — a numeric enum, spelled here so the type never has to be imported. */\nconst HTTP = 4;\n\n/** A buffer is not a URL, so a held name never compares equal to a lent one. */\nconst HELD = Symbol(\"held\");\n\nasync function boot(): Promise<Engine> {\n  const connector = wasmConnector();\n  const coordinator = new Coordinator(connector);\n  const db = (await connector.getDuckDB()) as unknown as Registry;\n  // Lent files are read lazily by range; caching their metadata is what keeps a pan from re-probing.\n  await coordinator.exec(\"SET enable_http_metadata_cache = true\");\n\n  const behind = new Map<string, string | typeof HELD>();\n\n  // Registry changes run one at a time: two `lend`s of one name racing each other would each see the\n  // old entry, and the second register would be refused.\n  let tail: Promise<unknown> = Promise.resolve();\n  const serial = (step: () => Promise<void>): Promise<void> => {\n    const run = tail.then(step);\n    tail = run.catch(() => {});\n    return run;\n  };\n\n  const release = async (name: string) => {\n    if (!behind.has(name)) return;\n    await db.dropFile(name);\n    behind.delete(name);\n  };\n\n  return {\n    coordinator,\n    query: (sql) =>\n      coordinator.query(sql, { type: \"json\", cache: false }) as Promise<Record<string, unknown>[]>,\n    lend: (files) =>\n      serial(async () => {\n        for (const [name, url] of Object.entries(files)) {\n          if (behind.get(name) === url) continue;\n          await release(name);\n          await db.registerFileURL(name, url, HTTP, false);\n          behind.set(name, url);\n        }\n      }),\n    hold: (name, bytes) =>\n      serial(async () => {\n        await release(name);\n        // A copy, because DuckDB-WASM transfers the buffer to its worker and detaches the caller's.\n        await db.registerFileBuffer(name, bytes.slice());\n        behind.set(name, HELD);\n      }),\n    drop: (names) =>\n      serial(async () => {\n        for (const name of names) await release(name);\n      }),\n  };\n}\n\n/**\n * Keyed on the document's global rather than on this module, so two copies of the package in one\n * bundle still share one database — which is the invariant, not the module identity.\n */\nconst KEY = Symbol.for(\"@kanzo-tech/mosaic/engine\");\n\n/** The page's one engine, booted on first ask. */\nexport function engine(): Promise<Engine> {\n  const scope = globalThis as { [KEY]?: Promise<Engine> };\n  scope[KEY] ??= boot();\n  return scope[KEY];\n}\n"],"names":["HTTP","HELD","boot","connector","wasmConnector","coordinator","Coordinator","db","behind","tail","serial","step","run","release","name","sql","files","url","bytes","names","KEY","engine","scope"],"mappings":";AAyCA,MAAMA,IAAO,GAGPC,IAAO,OAAO,MAAM;AAE1B,eAAeC,IAAwB;AACrC,QAAMC,IAAYC,EAAA,GACZC,IAAc,IAAIC,EAAYH,CAAS,GACvCI,IAAM,MAAMJ,EAAU,UAAA;AAE5B,QAAME,EAAY,KAAK,uCAAuC;AAE9D,QAAMG,wBAAa,IAAA;AAInB,MAAIC,IAAyB,QAAQ,QAAA;AACrC,QAAMC,IAAS,CAACC,MAA6C;AAC3D,UAAMC,IAAMH,EAAK,KAAKE,CAAI;AAC1B,WAAAF,IAAOG,EAAI,MAAM,MAAM;AAAA,IAAC,CAAC,GAClBA;AAAA,EACT,GAEMC,IAAU,OAAOC,MAAiB;AACtC,IAAKN,EAAO,IAAIM,CAAI,MACpB,MAAMP,EAAG,SAASO,CAAI,GACtBN,EAAO,OAAOM,CAAI;AAAA,EACpB;AAEA,SAAO;AAAA,IACL,aAAAT;AAAA,IACA,OAAO,CAACU,MACNV,EAAY,MAAMU,GAAK,EAAE,MAAM,QAAQ,OAAO,IAAO;AAAA,IACvD,MAAM,CAACC,MACLN,EAAO,YAAY;AACjB,iBAAW,CAACI,GAAMG,CAAG,KAAK,OAAO,QAAQD,CAAK;AAC5C,QAAIR,EAAO,IAAIM,CAAI,MAAMG,MACzB,MAAMJ,EAAQC,CAAI,GAClB,MAAMP,EAAG,gBAAgBO,GAAMG,GAAKjB,GAAM,EAAK,GAC/CQ,EAAO,IAAIM,GAAMG,CAAG;AAAA,IAExB,CAAC;AAAA,IACH,MAAM,CAACH,GAAMI,MACXR,EAAO,YAAY;AACjB,YAAMG,EAAQC,CAAI,GAElB,MAAMP,EAAG,mBAAmBO,GAAMI,EAAM,OAAO,GAC/CV,EAAO,IAAIM,GAAMb,CAAI;AAAA,IACvB,CAAC;AAAA,IACH,MAAM,CAACkB,MACLT,EAAO,YAAY;AACjB,iBAAWI,KAAQK,EAAO,OAAMN,EAAQC,CAAI;AAAA,IAC9C,CAAC;AAAA,EAAA;AAEP;AAMA,MAAMM,IAAM,OAAO,IAAI,2BAA2B;AAG3C,SAASC,IAA0B;AACxC,QAAMC,IAAQ;AACd,SAAAA,EAAAF,OAAAE,EAAAF,KAAelB,EAAA,IACRoB,EAAMF,CAAG;AAClB;"}

package/dist/index.d.ts

@@ -20,10 +20,16 @@
  * `Selection` is what makes one copy of Mosaic the easy outcome, and two copies would be two
  * crossfilters that never hear each other.
  */
-export { Coordinator, MosaicClient, Selection, makeClient, clausePoint, clausePoints, clauseInterval, clauseIntervals, clauseMatch, wasmConnector, type SelectionClause, } from '@uwdata/mosaic-core';
+export { Coordinator, MosaicClient, Selection, makeClient, clausePoint, clausePoints, clauseInterval, clauseIntervals, clauseMatch, type SelectionClause, } from '@uwdata/mosaic-core';
 export { Query, asc, desc, loadCSV, loadJSON, loadObjects, loadParquet, loadSpatial, loadExtension, type ExprValue, type FilterExpr, } from '@uwdata/mosaic-sql';
 /** Ours: turning an Arrow answer into values, which the client protocol does not do for you. */
 export { column, fillColumn, numbers, type NumericArray } from './arrow.js';
 /** Ours: the crossfilter adapter for a view whose positions are not in the database. */
 export { IdSetClient, type IdSetClientOptions } from './id-set-client.js';
+/**
+ * Ours: the page's one DuckDB-WASM engine — the coordinator and the file registry beside it. It is
+ * the only door to `wasmConnector`, which is why that is no longer re-exported: a second boot is a
+ * second database, and every host that wrote its own boot also wrote its own registry policy.
+ */
+export { engine, type Engine } from './engine.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,WAAW,EACX,aAAa,EACb,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,KAAK,EACL,GAAG,EACH,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAE5B,gGAAgG;AAChG,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5E,wFAAwF;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,WAAW,EACX,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,KAAK,EACL,GAAG,EACH,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAE5B,gGAAgG;AAChG,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5E,wFAAwF;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE1E;;;;GAIG;AACH,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,30 +1,31 @@
-import { Coordinator as a, MosaicClient as l, Selection as t, clauseInterval as n, clauseIntervals as r, clauseMatch as s, clausePoint as c, clausePoints as i, makeClient as u, wasmConnector as d } from "@uwdata/mosaic-core";
-import { Query as C, asc as f, desc as p, loadCSV as x, loadExtension as S, loadJSON as I, loadObjects as P, loadParquet as b, loadSpatial as v } from "@uwdata/mosaic-sql";
-import { column as O, fillColumn as h, numbers as j } from "./arrow.js";
-import { IdSetClient as q } from "./id-set-client.js";
+import { Coordinator as l, MosaicClient as a, Selection as t, clauseInterval as r, clauseIntervals as n, clauseMatch as s, clausePoint as c, clausePoints as i, makeClient as u } from "@uwdata/mosaic-core";
+import { Query as m, asc as f, desc as p, loadCSV as x, loadExtension as C, loadJSON as S, loadObjects as I, loadParquet as P, loadSpatial as b } from "@uwdata/mosaic-sql";
+import { column as M, fillColumn as O, numbers as g } from "./arrow.js";
+import { IdSetClient as j } from "./id-set-client.js";
+import { engine as q } from "./engine.js";
 export {
-  a as Coordinator,
-  q as IdSetClient,
-  l as MosaicClient,
-  C as Query,
+  l as Coordinator,
+  j as IdSetClient,
+  a as MosaicClient,
+  m as Query,
   t as Selection,
   f as asc,
-  n as clauseInterval,
-  r as clauseIntervals,
+  r as clauseInterval,
+  n as clauseIntervals,
   s as clauseMatch,
   c as clausePoint,
   i as clausePoints,
-  O as column,
+  M as column,
   p as desc,
-  h as fillColumn,
+  q as engine,
+  O as fillColumn,
   x as loadCSV,
-  S as loadExtension,
-  I as loadJSON,
-  P as loadObjects,
-  b as loadParquet,
-  v as loadSpatial,
+  C as loadExtension,
+  S as loadJSON,
+  I as loadObjects,
+  P as loadParquet,
+  b as loadSpatial,
   u as makeClient,
-  j as numbers,
-  d as wasmConnector
+  g as numbers
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanzo-tech/mosaic",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The Mosaic conversation, without React — coordinator, clients and clauses re-exported as one surface, plus the Arrow column reader and the id-set client that every consumer of them was writing by hand.",
   "type": "module",
   "license": "MIT",