@xenosystem/blocks 0.4.1 → 0.5.0

package/dist/auth/index.js

@@ -1,3 +1,5 @@
+import "../chunk-2KG3PWR4.js";
+
 // src/auth/gate/panel.ts
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";

package/dist/chunk-2KG3PWR4.js

@@ -0,0 +1,17 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+
+export {
+  __reExport
+};

package/dist/chunk-DJJGZ6U4.js

@@ -0,0 +1,215 @@
+// src/data/connectors/executors/sqlBuilder.ts
+import { isFilterGroup } from "@xenosystem/data-core";
+function quoteIdent(name) {
+  return `"${String(name).replace(/"/g, '""')}"`;
+}
+function quoteLiteral(value) {
+  if (value === null || value === void 0) return "NULL";
+  if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? String(value) : "NULL";
+  }
+  if (Array.isArray(value)) return `(${value.map((v) => quoteLiteral(v)).join(", ")})`;
+  if (typeof value === "object") return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+function isSafeTableName(name) {
+  return /^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(name);
+}
+function buildSelect(options) {
+  const { table, query, limit } = options;
+  if (!isSafeTableName(table)) return { error: `"${table}" is not a usable table name.` };
+  const known = options.columns ? new Set(options.columns) : null;
+  const unknown = (id) => known !== null && !known.has(id);
+  const groupBy = query.groupBy ?? [];
+  const aggregates = query.aggregates ?? [];
+  const projection = [];
+  if (groupBy.length > 0 || aggregates.length > 0) {
+    for (const level of groupBy) {
+      if (unknown(level.columnId)) return { error: `There is no column called "${level.columnId}".` };
+      projection.push(quoteIdent(level.columnId));
+    }
+    for (const aggregate of aggregates) {
+      const rendered = renderAggregate(aggregate, unknown);
+      if ("error" in rendered) return rendered;
+      projection.push(`${rendered.sql} AS ${quoteIdent(aggregate.id)}`);
+    }
+  } else if (query.select && query.select.length > 0) {
+    for (const columnId of query.select) {
+      if (unknown(columnId)) return { error: `There is no column called "${columnId}".` };
+      projection.push(quoteIdent(columnId));
+    }
+  }
+  const parts = [`SELECT ${projection.length > 0 ? projection.join(", ") : "*"}`];
+  parts.push(`FROM ${quoteIdent(table)}`);
+  if (query.filters) {
+    const where = renderFilterGroup(query.filters, unknown);
+    if ("error" in where) return where;
+    if (where.sql !== "") parts.push(`WHERE ${where.sql}`);
+  }
+  if (groupBy.length > 0) {
+    parts.push(`GROUP BY ${groupBy.map((level) => quoteIdent(level.columnId)).join(", ")}`);
+  }
+  if (query.sorts && query.sorts.length > 0) {
+    const terms = [];
+    for (const sort of query.sorts) {
+      const isAlias = aggregates.some((a) => a.id === sort.columnId);
+      if (!isAlias && unknown(sort.columnId)) {
+        return { error: `There is no column called "${sort.columnId}".` };
+      }
+      const direction = sort.direction === "desc" ? "DESC" : "ASC";
+      const nulls = sort.nulls === "first" ? "NULLS FIRST" : "NULLS LAST";
+      terms.push(`${quoteIdent(sort.columnId)} ${direction} ${nulls}`);
+    }
+    parts.push(`ORDER BY ${terms.join(", ")}`);
+  }
+  parts.push(`LIMIT ${Math.max(0, Math.floor(limit))}`);
+  if (options.offset && options.offset > 0) parts.push(`OFFSET ${Math.floor(options.offset)}`);
+  return { sql: parts.join(" ") };
+}
+function renderAggregate(aggregate, unknown) {
+  const column = quoteIdent(aggregate.columnId);
+  if (aggregate.fn !== "count" && unknown(aggregate.columnId)) {
+    return { error: `There is no column called "${aggregate.columnId}".` };
+  }
+  switch (aggregate.fn) {
+    case "count":
+      return { sql: "count(*)" };
+    case "countDistinct":
+      return { sql: `count(DISTINCT ${column})` };
+    case "countNumbers":
+      return { sql: `count(TRY_CAST(${column} AS DOUBLE))` };
+    case "sum":
+      return { sql: `sum(${column})` };
+    case "avg":
+      return { sql: `avg(${column})` };
+    case "min":
+      return { sql: `min(${column})` };
+    case "max":
+      return { sql: `max(${column})` };
+    case "median":
+    case "p50":
+      return { sql: `median(${column})` };
+    case "p90":
+      return { sql: `quantile_cont(${column}, 0.90)` };
+    case "p95":
+      return { sql: `quantile_cont(${column}, 0.95)` };
+    case "p99":
+      return { sql: `quantile_cont(${column}, 0.99)` };
+    case "stdev":
+      return { sql: `stddev_samp(${column})` };
+    case "var":
+      return { sql: `var_samp(${column})` };
+    case "product":
+      return { sql: `product(${column})` };
+    case "first":
+      return { sql: `first(${column})` };
+    case "last":
+      return { sql: `last(${column})` };
+    default:
+      return { error: `The aggregate "${String(aggregate.fn)}" is not supported by this source.` };
+  }
+}
+function renderFilterGroup(group, unknown = () => false) {
+  const parts = [];
+  for (const member of group.filters) {
+    const rendered = isFilterGroup(member) ? renderFilterGroup(member, unknown) : renderFilter(member, unknown);
+    if ("error" in rendered) return rendered;
+    if (rendered.sql !== "") parts.push(`(${rendered.sql})`);
+  }
+  if (parts.length === 0) return { sql: "" };
+  const joined = parts.join(group.combinator === "or" ? " OR " : " AND ");
+  return { sql: group.negate ? `NOT (${joined})` : joined };
+}
+function renderFilter(filter, unknown) {
+  if (unknown(filter.columnId)) return { error: `There is no column called "${filter.columnId}".` };
+  const column = quoteIdent(filter.columnId);
+  const insensitive = filter.caseInsensitive !== false;
+  const text = insensitive ? `lower(CAST(${column} AS VARCHAR))` : `CAST(${column} AS VARCHAR)`;
+  const like = (pattern) => `${text} LIKE ${quoteLiteral(insensitive ? pattern.toLowerCase() : pattern)}`;
+  const escaped = escapeLikePattern(String(filter.value ?? ""));
+  switch (filter.op) {
+    case "eq":
+      return { sql: filter.value === null ? `${column} IS NULL` : `${column} = ${quoteLiteral(filter.value)}` };
+    case "ne":
+      return { sql: filter.value === null ? `${column} IS NOT NULL` : `${column} IS DISTINCT FROM ${quoteLiteral(filter.value)}` };
+    case "gt":
+      return { sql: `${column} > ${quoteLiteral(filter.value)}` };
+    case "gte":
+      return { sql: `${column} >= ${quoteLiteral(filter.value)}` };
+    case "lt":
+      return { sql: `${column} < ${quoteLiteral(filter.value)}` };
+    case "lte":
+      return { sql: `${column} <= ${quoteLiteral(filter.value)}` };
+    case "contains":
+      return { sql: `${like(`%${escaped}%`)} ESCAPE '\\'` };
+    case "notContains":
+      return { sql: `NOT (${like(`%${escaped}%`)} ESCAPE '\\')` };
+    case "startsWith":
+      return { sql: `${like(`${escaped}%`)} ESCAPE '\\'` };
+    case "endsWith":
+      return { sql: `${like(`%${escaped}`)} ESCAPE '\\'` };
+    case "in":
+    case "notIn": {
+      const values = filter.values ?? [];
+      if (values.length === 0) return { sql: filter.op === "in" ? "FALSE" : "TRUE" };
+      const list = values.map((v) => quoteLiteral(v)).join(", ");
+      return { sql: `${column} ${filter.op === "in" ? "IN" : "NOT IN"} (${list})` };
+    }
+    case "between": {
+      const [low, high] = filter.values ?? [];
+      if (low === void 0 || high === void 0) {
+        return { error: `The "between" filter on "${filter.columnId}" needs two values.` };
+      }
+      return { sql: `${column} BETWEEN ${quoteLiteral(low)} AND ${quoteLiteral(high)}` };
+    }
+    case "isEmpty":
+      return { sql: `(${column} IS NULL OR CAST(${column} AS VARCHAR) = '')` };
+    case "isNotEmpty":
+      return { sql: `(${column} IS NOT NULL AND CAST(${column} AS VARCHAR) <> '')` };
+    case "relative": {
+      const n = Number(filter.n);
+      if (!Number.isFinite(n)) return { error: `The relative filter on "${filter.columnId}" has no window.` };
+      const unit = relativeUnit(filter.unit);
+      if (!unit) return { error: `The time unit "${String(filter.unit)}" is not supported by this source.` };
+      const sign = n < 0 ? "-" : "+";
+      const magnitude = Math.abs(Math.floor(n));
+      const bound = `now() ${sign} INTERVAL ${magnitude} ${unit}`;
+      return { sql: n < 0 ? `${column} BETWEEN ${bound} AND now()` : `${column} BETWEEN now() AND ${bound}` };
+    }
+    default:
+      return { error: `The filter "${String(filter.op)}" is not supported by this source.` };
+  }
+}
+function relativeUnit(unit) {
+  switch (unit) {
+    case "minute":
+      return "MINUTE";
+    case "hour":
+      return "HOUR";
+    case "day":
+      return "DAY";
+    case "week":
+      return "WEEK";
+    case "month":
+      return "MONTH";
+    case "quarter":
+      return "QUARTER";
+    case "year":
+      return "YEAR";
+    default:
+      return null;
+  }
+}
+function escapeLikePattern(text) {
+  return text.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+
+export {
+  quoteIdent,
+  quoteLiteral,
+  isSafeTableName,
+  buildSelect,
+  renderFilterGroup,
+  escapeLikePattern
+};

package/dist/data/duckdb.d.ts

@@ -0,0 +1,123 @@
+import { X as XenoSqlEngine } from '../transport-B1cdciP8.js';
+import '@xenosystem/data-core';
+
+/**
+ * The DuckDB-WASM adapter — the ONLY file in this package that knows DuckDB exists.
+ *
+ * Ships on the `./duckdb` subpath, imports its engine through `await import(...)`, and declares
+ * `@duckdb/duckdb-wasm` as an **optional peer**. A consumer that never opens a SQL source installs
+ * nothing and pays nothing; a host that already owns a DuckDB instance implements the three-method
+ * {@link XenoSqlEngine} seam against its own and ignores this file entirely.
+ *
+ * The measured cost of getting that wrong: `duckdb-eh.wasm` is **34 MB raw / ~7.1 MB brotli**, plus
+ * a 0.74 MB worker. A static import would put that on every consumer of `@xenosystem/blocks/data`,
+ * including the twenty panels that never run SQL. The lucide incident already taught this package
+ * that lesson once.
+ *
+ * ## Four traps, each closed deliberately
+ *
+ * Every one of these is a documented, currently-open failure mode. They are why this adapter is
+ * ~200 lines rather than ~40.
+ *
+ * 1. **Never `insertArrowTable(tableFromJSON(rows))`.** Arrow's `tableFromJSON` infers
+ *    `Dictionary<Utf8, Int32>` for string columns, and duckdb-wasm's IPC decoder does not accept
+ *    dictionary-encoded streams. The failure is *silent*: no error, no rows, and then
+ *    `Catalog Error: Table with name X does not exist` on the next query. Compounding it,
+ *    `insertArrowTable` gates on `input instanceof Table`, which is `false` whenever the bundler
+ *    resolves two copies of `apache-arrow` — and duckdb-wasm pins `^17` while npm serves 21.x.
+ *    This adapter uses the JSON path instead, which has neither problem.
+ *
+ * 2. **Never `read_json_auto`.** DuckDB-WASM builds `json`, `parquet`, `icu` and `autocomplete` as
+ *    `DONT_LINK`, so they are **autoloaded over the network** from `extensions.duckdb.org` at first
+ *    use. In a sandbox, an offline app or a web export that is a hang or a CORS error — in the one
+ *    code path whose entire selling point is that it needs no network.
+ *    `insertJSONFromPath` is implemented in duckdb-wasm's own C++ against Arrow's JSON reader and
+ *    touches no extension, so it works with zero network. Autoloading is then turned **off**, so a
+ *    stray `read_parquet` fails loudly instead of hanging.
+ *
+ * 3. **`StructRowProxy.toJSON()` is shallow.** Nested structs stay proxies and list columns stay
+ *    Arrow `Vector`s, so a naive `.toJSON()` hands the panel objects it cannot render and
+ *    `JSON.stringify` cannot serialize. {@link unwrapArrowValue} descends.
+ *
+ * 4. **BIGINT arrives as `bigint`.** `count(*)` is BIGINT, so the single most common aggregate in
+ *    existence makes `JSON.stringify` throw `Do not know how to serialize a BigInt`. DECIMAL arrives
+ *    as a raw `Uint32Array` of 128-bit limbs; timestamps as epoch numbers, not `Date`. The config
+ *    casts what it can and {@link unwrapArrowValue} handles the rest.
+ *
+ * @module
+ */
+
+/**
+ * The bundle assets, which the **host** must provide.
+ *
+ * There is deliberately no jsDelivr default. `getJsDelivrBundles()` would make the "zero
+ * capabilities, works offline, survives a web export" promise false the first time it ran, by
+ * fetching 34 MB from a third-party CDN. A host that wants the CDN can pass those URLs explicitly
+ * and will have made that choice on purpose.
+ */
+interface DuckDbBundle {
+    /** URL of `duckdb-eh.wasm` (or `duckdb-mvp.wasm`). */
+    mainModule: string;
+    /** URL of the matching worker script. */
+    mainWorker: string;
+    /** Only for the cross-origin-isolated bundle. */
+    pthreadWorker?: string | null;
+}
+/** Options for {@link createDuckDbEngine}. */
+interface CreateDuckDbEngineOptions {
+    /** Where the wasm and worker live. Host-supplied — see {@link DuckDbBundle}. */
+    bundle: DuckDbBundle;
+    /**
+     * Pre-built module, for a host that already imported or vendored duckdb-wasm.
+     *
+     * Supplying this skips the dynamic import entirely, which is how an Electron host that bundles
+     * the package avoids a second copy.
+     */
+    module?: unknown;
+    /** A ready `AsyncDuckDB`. Supplying it skips instantiation altogether. */
+    db?: unknown;
+    /** Log query text. Off by default — a raw statement can embed user data. */
+    debug?: boolean;
+}
+/**
+ * Build an {@link XenoSqlEngine} backed by DuckDB-WASM.
+ *
+ * @param options - The bundle URLs, or a pre-built instance.
+ * @returns The engine seam, ready to hand to `createConnectorsPanel({ transport: { sql } })`.
+ *
+ * @example
+ * ```ts
+ * const sql = await createDuckDbEngine({
+ *   bundle: { mainModule: wasmUrl, mainWorker: workerUrl },
+ * })
+ * const panel = createConnectorsPanel({ transport: { fetch: browserFetch(), sql } })
+ * ```
+ */
+declare function createDuckDbEngine(options: CreateDuckDbEngineOptions): Promise<XenoSqlEngine>;
+/**
+ * Convert one Arrow row proxy into a plain object.
+ *
+ * @param row - A `StructRowProxy` from `Table.toArray()`.
+ * @returns A plain, serializable object.
+ */
+declare function unwrapArrowRow(row: unknown): Record<string, unknown>;
+/**
+ * Recursively convert an Arrow value into something plain and serializable.
+ *
+ * TRAP 3 and the tail of TRAP 4 both live here. `toJSON()` on a row is **shallow**: a nested struct
+ * comes back as another proxy and a list column as an Arrow `Vector`, neither of which a panel can
+ * render or a `.xapp` can hold. And a `bigint` that survived the config cast — DuckDB's HUGEINT, or
+ * any build where the cast flag was ignored — would make `JSON.stringify` throw outright.
+ *
+ * @param value - Any value out of an Arrow row.
+ * @returns A plain value.
+ *
+ * @example
+ * ```ts
+ * unwrapArrowValue(123n)                     // → 123
+ * unwrapArrowValue(9007199254740993n)        // → '9007199254740993'  (precision kept, as text)
+ * ```
+ */
+declare function unwrapArrowValue(value: unknown): unknown;
+
+export { type CreateDuckDbEngineOptions, type DuckDbBundle, createDuckDbEngine, unwrapArrowRow, unwrapArrowValue };

package/dist/data/duckdb.js

@@ -0,0 +1,142 @@
+import {
+  isSafeTableName
+} from "../chunk-DJJGZ6U4.js";
+import "../chunk-2KG3PWR4.js";
+
+// src/data/connectors/duckdb.ts
+async function createDuckDbEngine(options) {
+  const duckdb = options.module ?? await importDuckDb();
+  let db = options.db;
+  let worker = null;
+  if (!db) {
+    worker = new Worker(options.bundle.mainWorker);
+    const Logger = options.debug ? duckdb.ConsoleLogger : duckdb.VoidLogger ?? duckdb.ConsoleLogger;
+    db = new duckdb.AsyncDuckDB(new Logger(), worker);
+    await db.instantiate(options.bundle.mainModule, options.bundle.pthreadWorker ?? null);
+  }
+  await db.open({
+    query: {
+      // TRAP 4: without these, `count(*)` returns a `bigint` that `JSON.stringify` refuses, and a
+      // DECIMAL returns a raw Uint32Array of 128-bit limbs.
+      castBigIntToDouble: true,
+      castDecimalToDouble: true
+    }
+  });
+  const connection = await db.connect();
+  await lockDown(connection);
+  const registered = /* @__PURE__ */ new Set();
+  return {
+    async register(tables) {
+      for (const table of tables) {
+        if (!isSafeTableName(table.name)) {
+          throw new Error(`"${table.name}" is not a usable table name.`);
+        }
+        const fileName = `${table.name}.json`;
+        await db.registerFileText(fileName, JSON.stringify(table.rows ?? []));
+        try {
+          await connection.insertJSONFromPath(fileName, {
+            schema: "main",
+            name: table.name,
+            // ROW_ARRAY: we know the shape, so inference is skipped.
+            shape: "row-array",
+            // Replace rather than append: a refresh must not double the rows.
+            create: true
+          });
+          registered.add(table.name);
+        } finally {
+          await db.dropFile(fileName).catch(() => {
+          });
+        }
+      }
+    },
+    async query(sql) {
+      const table = await connection.query(sql);
+      return table.toArray().map((row) => unwrapArrowRow(row));
+    },
+    async dispose() {
+      for (const name of registered) {
+        await connection.query(`DROP TABLE IF EXISTS ${JSON.stringify(name)}`).catch(() => {
+        });
+      }
+      registered.clear();
+      await connection.close().catch(() => {
+      });
+      if (!options.db) await db?.terminate().catch(() => {
+      });
+      worker?.terminate();
+    }
+  };
+}
+async function importDuckDb() {
+  try {
+    const specifier = "@duckdb/duckdb-wasm";
+    return await import(
+      /* @vite-ignore */
+      /* webpackIgnore: true */
+      specifier
+    );
+  } catch (error) {
+    throw new Error(
+      "In-memory SQL needs @duckdb/duckdb-wasm, which is not installed. Install it, or supply a SQL engine through the transport seam. " + (error instanceof Error ? error.message : "")
+    );
+  }
+}
+async function lockDown(connection) {
+  const statements = [
+    "SET enable_external_access = false",
+    "SET autoinstall_known_extensions = false",
+    "SET autoload_known_extensions = false",
+    "SET allow_community_extensions = false",
+    // LAST. Anything after this cannot be changed.
+    "SET lock_configuration = true"
+  ];
+  for (const statement of statements) {
+    await connection.query(statement).catch(() => {
+    });
+  }
+}
+function unwrapArrowRow(row) {
+  if (row === null || row === void 0) return {};
+  const shallow = typeof row.toJSON === "function" ? row.toJSON() : row;
+  const out = {};
+  for (const [key, value] of Object.entries(shallow)) out[key] = unwrapArrowValue(value);
+  return out;
+}
+function unwrapArrowValue(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "bigint") {
+    return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : value.toString();
+  }
+  if (typeof value !== "object") return value;
+  if (value instanceof Date) return value.toISOString();
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+    return Array.from(value, (item) => unwrapArrowValue(item));
+  }
+  if (Array.isArray(value)) return value.map((item) => unwrapArrowValue(item));
+  const vector = value;
+  if (typeof vector.toArray === "function") {
+    return vector.toArray().map((item) => unwrapArrowValue(item));
+  }
+  const nested = value;
+  if (typeof nested.toJSON === "function") {
+    const plain = nested.toJSON();
+    if (plain !== null && typeof plain === "object" && !Array.isArray(plain)) {
+      const out2 = {};
+      for (const [key, item] of Object.entries(plain)) {
+        out2[key] = unwrapArrowValue(item);
+      }
+      return out2;
+    }
+    return plain;
+  }
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    out[key] = unwrapArrowValue(item);
+  }
+  return out;
+}
+export {
+  createDuckDbEngine,
+  unwrapArrowRow,
+  unwrapArrowValue
+};