okmodel 0.6.0 → 0.8.0

package/dist/tooling/driver-test.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `okm driver test`.
+ *
+ * The runner lives in the harness and reuses the conformance suites. This
+ * file only finds that runner and prints what it writes. Tooling does not
+ * import the harness.
+ */
+/**
+ * Runs the conformance suites for the driver named on the command line.
+ *
+ * `<driver>` is `pglite`, `postgresjs`, `pg`, `bun`, `neon`, or a module path.
+ * `--url` is the Postgres URL. `pglite` does not use it. The other built-in
+ * drivers need `--url` or `DATABASE_URL`. A module whose export sets
+ * `memory: true` does not need a URL.
+ *
+ * The report is one header (`driver`, `dialect postgres`) and one row per
+ * case: id, behavior, result (`pass`, `fail`, or `unsupported`), and the
+ * capability when the result is unsupported. A failure exits through
+ * {@link OkmError}. An unsupported case does not.
+ *
+ * @param args - Arguments after `driver test`
+ * @param stdout - Where the report is written
+ */
+export declare function driverTest(args: readonly string[], stdout: (text: string) => void): Promise<void>;
+/**
+ * Path of the `okm driver test` runner.
+ *
+ * A source checkout finds `packages/harness/src/driver-run.ts` and the
+ * command spawns `bun`. The packed build writes
+ * `dist/tooling/driver-run.js`. Splitting puts this module in
+ * `dist/shared/`, so that file is one directory up from the chunk.
+ *
+ * @param here - Directory of this module
+ * @returns Runner path. The caller checks that the file exists
+ */
+export declare function driverRunnerPath(here: string): string;

package/dist/tooling/migrate/commands.d.ts

@@ -22,8 +22,8 @@ export declare function formatFailure(error: unknown, verbose?: boolean): string
  * Runs one `okm` invocation.
  *
  * `--version` stays in the bin. This function handles `build`, `check`,
- * `generate`, `dev`, `push`, `seed`, `ext list`, `ext check`, `doctor`, and
- * `migrate plan`, `apply`, `status`, and `check`.
+ * `generate`, `dev`, `push`, `seed`, `ext list`, `ext check`, `doctor`,
+ * `driver test`, and `migrate plan`, `apply`, `status`, and `check`.
  *
  * @param argv - Arguments after the program name
  * @param io - Working directory and stdout. Defaults to the process

package/dist/tooling/migrate/engine.d.ts

@@ -1,8 +1,9 @@
 /**
  * Engine-version checks `okm migrate apply` runs before the first statement.
  *
- * The only engine-dependent feature in 0.2 is a `uuidv7()` database default,
- * which Postgres has from 18. Nothing here is reachable from `connect()`.
+ * An explicit `uuidv7()` database default needs {@link UUIDV7_POSTGRES}.
+ * A bare `t.id()` stores `gen_random_uuid()` and does not match here.
+ * Nothing here is reachable from `connect()`.
  */
 import type { DriverConnection } from "../../contracts/driver.js";
 import type { StoredMigration } from "./files.js";

package/dist/tooling/migrate/index.js

@@ -1,27 +1,27 @@
-import"../../shared/wkme6tep.js";
-import"../../shared/qq3899ht.js";
+import"../../shared/35q0n9tz.js";
+import"../../shared/12z7aznj.js";
 import"../../shared/n442h54c.js";
 import {
   applyTarget2,
   backfillTiming2
-} from "../../shared/nx9hh281.js";
+} from "../../shared/pan0370z.js";
 import {
   readReference
-} from "../../shared/p248q79y.js";
-import"../../shared/knmes2kh.js";
-import"../../shared/vjpnzwjz.js";
+} from "../../shared/mnvjvqyp.js";
+import"../../shared/kj9d8maq.js";
+import"../../shared/p3xbdcvt.js";
 import {
   projectPath,
   loadMigrations,
   loadHeadSnapshot,
   loadBuiltSchema,
   loadConfig
-} from "../../shared/t3g0k88x.js";
+} from "../../shared/f4jy1j7x.js";
 import {
   assertTargetPolicy,
   selectTarget
-} from "../../shared/ttmg09vd.js";
-import"../../shared/9s0ypp87.js";
+} from "../../shared/dpc2r7rb.js";
+import"../../shared/sjk86yrx.js";
 import {
   OkmError2
 } from "../../shared/52szzakm.js";

package/dist/tooling/migrate/project.d.ts

@@ -72,6 +72,9 @@ export declare function checkProject(cwd: string, flags?: InvokeFlags): Promise<
 /**
  * Table files whose names do not appear in the schema module.
  *
+ * The stem is compared without case, so `Tasks.ts` matches `tasks` in the
+ * schema text. A case-insensitive volume still loads that import.
+ *
  * @param schemaSource - Source text of the schema module
  * @param fileNames - File names in the tables directory
  * @returns Files `okm check` reports as OKM1024

package/dist/tooling/shared/03k6res6.js

@@ -0,0 +1,210 @@
+import {
+  OkmError,
+  tag
+} from "./f9mphxej.js";
+
+// src/dialects/pg/filter-parse.ts
+var PARSED = [
+  "eq",
+  "in",
+  "inList",
+  "notIn",
+  "lt",
+  "lte",
+  "gt",
+  "gte",
+  "between",
+  "startsWith",
+  "endsWith",
+  "contains",
+  "like",
+  "ilike",
+  "not",
+  "containedBy",
+  "overlaps",
+  "hasKey",
+  "hasAnyKey"
+];
+var PARSED_OPS = `,${PARSED.join(",")},`;
+var PARSED_FIX = "Use eq, in, notIn, lt, lte, gt, gte, between, startsWith, endsWith, contains, like, ilike, not, containedBy, overlaps, hasKey, or hasAnyKey.";
+function parseQuery(allow, sort, query, relations) {
+  if (typeof query !== "object" || query === null || Array.isArray(query)) {
+    throw new OkmError("OKM1121", "filters parse expects an object of fields.");
+  }
+  for (const field of Object.keys(allow)) {
+    for (const op of allow[field] ?? []) {
+      if (PARSED_OPS.includes(`,${op},`))
+        continue;
+      throw new OkmError("OKM1120", `filters() cannot apply ${op} on ${field}.`, {
+        fix: { summary: PARSED_FIX }
+      });
+    }
+  }
+  const nested = relations ?? {};
+  const whereParts = [];
+  let orderBy;
+  for (const key of Object.keys(query)) {
+    const value = query[key];
+    if (key === "sort" && typeof value === "string" && sort.includes(value)) {
+      orderBy = { [value]: "asc" };
+      continue;
+    }
+    if (Object.hasOwn(allow, key)) {
+      whereParts.push(...clauses(key, allow[key] ?? [], value));
+      continue;
+    }
+    if (Object.hasOwn(nested, key)) {
+      whereParts.push(relationClause(key, nested[key] ?? [], value));
+      continue;
+    }
+    throw new OkmError("OKM1123", `Field ${key} is not in the allow list.`, {
+      fix: { summary: "Remove the field, or add it to filters({ allow }) or relations." }
+    });
+  }
+  const where = combine(whereParts);
+  return orderBy === undefined ? { where } : { where, orderBy };
+}
+function clauses(field, ops, value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    if (!ops.includes("eq")) {
+      throw new OkmError("OKM1120", `filters() cannot apply eq on ${field}.`, {
+        fix: { summary: "Add eq to that field, or send an object of allowed operators." }
+      });
+    }
+    return [{ [field]: value }];
+  }
+  const applied = [];
+  for (const op of Object.keys(value)) {
+    if (!Object.hasOwn(value, op))
+      continue;
+    if (!ops.includes(op) && !(op === "inList" && ops.includes("in"))) {
+      throw new OkmError("OKM1120", `filters() cannot apply ${op} on ${field}.`, {
+        fix: { summary: "Send an operator that field's allow list names." }
+      });
+    }
+    applied.push(one(field, op, value[op]));
+  }
+  if (applied.length === 0) {
+    throw new OkmError("OKM1120", `filters() cannot apply a value on ${field}.`, {
+      fix: { summary: "Send eq as a scalar, or an object of allowed operators." }
+    });
+  }
+  return applied;
+}
+function one(field, op, value) {
+  switch (op) {
+    case "eq":
+      return {
+        [field]: value !== null && typeof value === "object" ? tag("eq", value) : value
+      };
+    case "in":
+    case "inList":
+      return { [field]: tag("inList", list(value, op)) };
+    case "notIn":
+      return { [field]: tag("notIn", list(value, op)) };
+    case "lt":
+      return { [field]: tag("lt", value) };
+    case "lte":
+      return { [field]: tag("lte", value) };
+    case "gt":
+      return { [field]: tag("gt", value) };
+    case "gte":
+      return { [field]: tag("gte", value) };
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) {
+        throw new OkmError("OKM1120", `between on ${field} needs two bounds.`, {
+          fix: { summary: "Send between as [from, to]." }
+        });
+      }
+      return { [field]: tag("between", [value[0], value[1]]) };
+    }
+    case "startsWith":
+      return { [field]: tag("startsWith", text(value, op)) };
+    case "endsWith":
+      return { [field]: tag("endsWith", text(value, op)) };
+    case "contains":
+      return { [field]: tag("contains", value) };
+    case "not":
+      if (value !== null && typeof value === "object") {
+        throw new OkmError("OKM1120", `not on ${field} takes a scalar.`, {
+          fix: { summary: "Send not a scalar or null. Nested operators are not accepted." }
+        });
+      }
+      return { [field]: tag("not", value) };
+    case "containedBy":
+      return { [field]: tag("containedBy", value) };
+    case "overlaps":
+      return { [field]: tag("overlaps", value) };
+    case "hasKey":
+      return { [field]: tag("hasKey", text(value, "hasKey")) };
+    case "hasAnyKey":
+      return { [field]: tag("hasAnyKey", strings(value, field)) };
+    case "like":
+      return { [field]: tag("like", text(value, op)) };
+    case "ilike":
+      return { [field]: tag("ilike", text(value, op)) };
+    default:
+      throw new OkmError("OKM1120", `filters() cannot apply ${op} on ${field}.`, {
+        fix: { summary: "Use an operator parse applies." }
+      });
+  }
+}
+function relationClause(name, fields, value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new OkmError("OKM1120", `filters() cannot apply a value on ${name}.`, {
+      fix: { summary: "Send the relation an object of allowlisted fields." }
+    });
+  }
+  const parts = [];
+  for (const field of Object.keys(value)) {
+    if (!Object.hasOwn(value, field))
+      continue;
+    if (!fields.includes(field)) {
+      throw new OkmError("OKM1123", `Field ${field} is not in the allow list.`, {
+        fix: { summary: "Remove the field, or add it to filters({ relations })." }
+      });
+    }
+    parts.push(...clauses(field, PARSED, value[field]));
+  }
+  if (parts.length === 0) {
+    throw new OkmError("OKM1120", `filters() cannot apply a value on ${name}.`, {
+      fix: { summary: "Send the relation an object of allowlisted fields." }
+    });
+  }
+  return { [name]: tag("has", combine(parts)) };
+}
+function combine(parts) {
+  const first = parts[0];
+  if (first === undefined)
+    return {};
+  if (parts.length === 1)
+    return first;
+  return tag("and", parts);
+}
+function list(value, op) {
+  if (!Array.isArray(value)) {
+    throw new OkmError("OKM1120", `${op} needs an array.`, {
+      fix: { summary: "Send that operator an array of values." }
+    });
+  }
+  return value;
+}
+function strings(value, field) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new OkmError("OKM1120", `hasAnyKey on ${field} needs an array of strings.`, {
+      fix: { summary: "Send hasAnyKey an array of strings." }
+    });
+  }
+  return value;
+}
+function text(value, op) {
+  if (typeof value !== "string") {
+    throw new OkmError("OKM1120", `${op} needs a string.`, {
+      fix: { summary: "Send that operator a string." }
+    });
+  }
+  return value;
+}
+export {
+  parseQuery
+};

package/dist/tooling/shared/08kemxjd.js

@@ -0,0 +1,10 @@
+import {
+  resetSession2,
+  resetQueried2,
+  refuseWhenLost2
+} from "./4d2w25vw.js";
+export {
+  refuseWhenLost2 as refuseWhenLost,
+  resetQueried2 as resetQueried,
+  resetSession2 as resetSession
+};

package/dist/tooling/shared/2revefqt.js

@@ -0,0 +1,209 @@
+import {
+  refusePrototypeKey
+} from "./ppnnnvj8.js";
+import {
+  throwNamed,
+  parseOrder,
+  projectExpr,
+  quote,
+  list,
+  isRecord,
+  fail2
+} from "./f9mphxej.js";
+
+// src/dialects/pg/ops/bucket.ts
+var RUNTIME = Symbol.for("okmodel.bucket");
+function isBucket(value) {
+  return typeof value === "object" && value !== null && RUNTIME in value;
+}
+
+// src/runtime/bucket-group.ts
+function readBucket(table, value, fields, aliases) {
+  if (!isBucket(value))
+    fail2("OKM1120", "bucket group");
+  const column = typeof value.column === "string" ? table.columns.get(value.column) : undefined;
+  if (typeof value.column !== "string" || column === undefined) {
+    throwNamed("OKM1120", String(value.column), table.names, `Field ${String(value.column)} is not on ${table.model.name}. Accepted names: ${list(table.names)}.`);
+  }
+  if (column.hidden) {
+    fail2("OKM1120", `Field ${column.field} is hidden, so groupBy cannot read it.`);
+  }
+  const unit = unitOf(value.unit);
+  if (unit === undefined) {
+    fail2("OKM1120", `bucket() unit ${String(value.unit)} is not a time unit. Accepted units: second, minute, hour, day, week, month, quarter, year.`);
+  }
+  const shift = weekShift(value.weekStart, unit);
+  const kind = temporalKind(column.dataType);
+  if (kind !== "timestamptz" && kind !== "date") {
+    fail2("OKM1120", `bucket() does not apply to ${kind === "timestamp" ? "timestamp" : column.dataType} column ${column.field}. Use timestamptz or date.`);
+  }
+  if (kind === "date" && clockUnit(unit)) {
+    fail2("OKM1120", `bucket() unit ${unit} does not apply to date column ${column.field}. Accepted units: day, week, month, quarter, year.`);
+  }
+  let tz;
+  if (kind === "timestamptz") {
+    if (typeof value.tz !== "string") {
+      fail2("OKM1120", `bucket() on timestamptz column ${column.field} needs tz, an IANA time zone.`);
+    }
+    if (!iana(value.tz))
+      fail2("OKM1120", `bucket() tz ${value.tz} is not an IANA time zone.`);
+    tz = value.tz;
+  } else if (value.tz !== undefined) {
+    fail2("OKM1120", `bucket() on date column ${column.field} does not take tz.`);
+  }
+  if (typeof value.as !== "string" || value.as.length === 0) {
+    fail2("OKM1120", "bucket() needs as, the name of the result key.");
+  }
+  refusePrototypeKey(value.as, "bucket as");
+  if (value.as === "count" || value.as === "sum" || value.as === "avg" || value.as === "min" || value.as === "max") {
+    fail2("OKM1120", `bucket as ${value.as} clashes with an aggregate key.`);
+  }
+  if (fields.has(value.as) || aliases.has(value.as)) {
+    fail2("OKM1120", `bucket as ${value.as} clashes with another group.`);
+  }
+  aliases.add(value.as);
+  return { kind: "bucket", column, unit, tz, as: value.as, shift, clock: clockUnit(unit) };
+}
+function writeBucket(sink, outputs, wrote, group) {
+  if (wrote.at > 0)
+    sink.text(", ");
+  if (group.clock)
+    emitClock(sink, group);
+  else
+    emitCalendar(sink, group);
+  outputs?.fields.push({
+    key: `g:${group.as}`,
+    at: wrote.at,
+    decode: bucketDecode(group)
+  });
+  wrote.at += 1;
+}
+function writeGrouped(sink, names, orderBy) {
+  sink.text(ordinals(names.length));
+  if (isRecord(orderBy) && Object.keys(orderBy).length > 0) {
+    sink.text(" order by ");
+    const keys = Object.keys(orderBy);
+    for (let index = 0;index < keys.length; index += 1) {
+      const key = keys[index];
+      if (key === undefined)
+        continue;
+      const parsed = parseOrder(key, orderBy[key]);
+      if (index > 0)
+        sink.text(", ");
+      sink.text(String(names.indexOf(key) + 1));
+      sink.text(parsed.dir === "asc" ? " asc" : " desc");
+      sink.text(parsed.nulls === "first" ? " nulls first" : " nulls last");
+      sink.mark(`o:${key}:${parsed.dir}:${parsed.nulls}`);
+    }
+    return;
+  }
+  sink.text(" order by ");
+  const parts = [];
+  for (let index = 1;index <= names.length; index += 1) {
+    parts.push(`${String(index)} asc nulls last`);
+  }
+  sink.text(parts.join(", "));
+}
+function unitOf(value) {
+  if (value === "second" || value === "minute" || value === "hour" || value === "day" || value === "week" || value === "month" || value === "quarter" || value === "year") {
+    return value;
+  }
+  return;
+}
+function clockUnit(unit) {
+  return unit === "second" || unit === "minute" || unit === "hour";
+}
+function weekShift(value, unit) {
+  if (value === undefined)
+    return 0;
+  if (unit !== "week")
+    fail2("OKM1120", "bucket() weekStart applies to unit week.");
+  if (value === "monday")
+    return 0;
+  if (value === "sunday")
+    return 1;
+  if (value === "saturday")
+    return 2;
+  return fail2("OKM1120", "bucket() weekStart must be monday, sunday, or saturday.");
+}
+function temporalKind(dataType) {
+  if (dataType === "date")
+    return "date";
+  if (dataType === "timestamptz" || dataType.startsWith("timestamptz("))
+    return "timestamptz";
+  if (dataType === "timestamp" || dataType.startsWith("timestamp("))
+    return "timestamp";
+  return;
+}
+function iana(tz) {
+  try {
+    Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function bucketDecode(group) {
+  if (group.clock || !group.column.dataType.startsWith("timestamptz"))
+    return group.column.decode;
+  return decodeDay;
+}
+function decodeDay(wire) {
+  const temporal = globalThis.Temporal;
+  if (typeof temporal !== "object" || temporal === null || !("PlainDate" in temporal)) {
+    return fail2("OKM1120", "Date and time codecs need the Temporal global. okmodel does not ship a polyfill. Use a runtime that provides Temporal, or assign a polyfill to globalThis.Temporal before using these columns.");
+  }
+  try {
+    return temporal.PlainDate.from(wire);
+  } catch {
+    return fail2("OKM1120", `date ${wire} must be YYYY-MM-DD.`);
+  }
+}
+var ZONE = "\x00";
+function emitClock(sink, group) {
+  const column = `t.${quote(group.column.sql)}`;
+  const wrapped = projectExpr(`date_trunc('${group.unit}', ${column}, ${ZONE})`, "timestamptz");
+  const at = wrapped.indexOf(ZONE);
+  sink.text(wrapped.slice(0, at));
+  sink.param(group.tz ?? "");
+  sink.text(wrapped.slice(at + ZONE.length));
+}
+function emitCalendar(sink, group) {
+  const column = `t.${quote(group.column.sql)}`;
+  sink.text("(date_trunc('");
+  sink.text(group.unit);
+  sink.text("', ");
+  emitLocal(sink, column, group.tz);
+  if (group.shift === 0) {
+    sink.text("))::date");
+    return;
+  }
+  const days = group.shift === 1 ? "1 day" : "2 days";
+  sink.text(" + interval '");
+  sink.text(days);
+  sink.text("') - interval '");
+  sink.text(days);
+  sink.text("')::date");
+}
+function emitLocal(sink, column, tz) {
+  if (tz === undefined) {
+    sink.text(column);
+    return;
+  }
+  sink.text("(");
+  sink.text(column);
+  sink.text(" AT TIME ZONE ");
+  sink.param(tz);
+  sink.text(")");
+}
+function ordinals(count) {
+  const parts = [];
+  for (let index = 1;index <= count; index += 1)
+    parts.push(String(index));
+  return parts.join(", ");
+}
+export {
+  readBucket,
+  writeBucket,
+  writeGrouped
+};