@schemic/core 0.1.0-alpha.0

package/lib/driver.d.ts

@@ -0,0 +1,150 @@
+export { T as ApplyOptions, A as Authored, a as AuthoredDef, U as ConnectionOverrides, a3 as Definable, c as Diff, d as DiffItem, D as Driver, W as EmitOptions, a7 as KindEngine, a8 as KindPlan, a9 as KindRegistry, aa as KindSnapshot, ab as KindSpec, Y as MigrationDirection, Z as MigrationRecord, _ as MigrationStore, ad as OrderNode, af as PortableObject, ah as Ref, R as ResolvedConfig, a0 as ShadowCapability, a1 as Statement, a2 as buildKindDiff, V as driverNames, a4 as emitKinds, X as getDriver, a5 as introspectKinds, ac as lowerSchema, ae as orderObjects, ag as planKinds, $ as registerDriver, aj as snapshotKinds, ak as snapshotObjects } from './driver-Dh5hLKHm.js';
+export { C as ConnectionConfigBase, a as ConnectionEntry, b as ConnectionInput, R as ResolveContext, c as connectionEntry } from './config-TIiKDd9t.js';
+import 'jiti';
+import 'commander';
+
+/**
+ * The portable scalar set — the common denominator every driver maps to a concrete column type and
+ * back. A driver MAY reject scalars it cannot represent (and authoring can pin a richer DB-native
+ * type via `{ t: "native" }`). Names are lowercase and dialect-neutral.
+ */
+type ScalarName = "any" | "bool" | "string" | "int" | "float" | "decimal" | "number" | "datetime" | "duration" | "uuid" | "bytes" | "null";
+/**
+ * A dialect-independent field type. Drivers translate this to their own type expression (`emitType`)
+ * and parse their introspection back into it (`parseType`). `option` and `nullable` are ORTHOGONAL
+ * and BOTH equality-relevant — see the note on `nullable` below; never collapse them.
+ */
+type PortableType = 
+/** A primitive scalar. */
+{
+    t: "scalar";
+    name: ScalarName;
+}
+/** A literal value type, e.g. the `'active'` in `'active' | 'archived'`. */
+ | {
+    t: "literal";
+    value: string | number | boolean;
+}
+/**
+ * The field may be ABSENT / NONE (Surreal `option<T>`; SQL "column omitted / has a DEFAULT").
+ * Orthogonal to `nullable`.
+ */
+ | {
+    t: "option";
+    inner: PortableType;
+}
+/**
+ * The field may be NULL (Surreal `T | null`; SQL `NULL` vs `NOT NULL`). Orthogonal to `option`:
+ * `option<T>`, `T | null`, and `option<T | null>` are THREE DISTINCT types. `normalize()` folds
+ * `nullable(option(X))` -> `option(nullable(X))` so `.optional().nullable()` ≡ `.nullish()`.
+ */
+ | {
+    t: "nullable";
+    inner: PortableType;
+}
+/** An ordered, possibly length-bounded list. */
+ | {
+    t: "array";
+    elem: PortableType;
+    size?: number;
+}
+/** A set (distinct elements), possibly length-bounded. */
+ | {
+    t: "set";
+    elem: PortableType;
+    size?: number;
+}
+/** A discriminated/plain union. `normalize()` keeps `members` canonically sorted. */
+ | {
+    t: "union";
+    members: PortableType[];
+}
+/** A nested object/record literal. `flexible` allows undeclared keys (Surreal FLEXIBLE). */
+ | {
+    t: "object";
+    fields: Record<string, PortableType>;
+    flexible?: boolean;
+}
+/**
+ * A link to a row in one of `tables` (Surreal `record<a | b>`; SQL foreign key). The id-VALUE type
+ * is intentionally NOT modelled here — the DDL never encodes it; it lives App/Wire-side (TS-only).
+ */
+ | {
+    t: "record";
+    tables: string[];
+}
+/** A geometry type (Surreal-native; PostGIS or unsupported elsewhere). */
+ | {
+    t: "geometry";
+    kind: GeometryKind;
+}
+/** The bottom type (no value). */
+ | {
+    t: "never";
+}
+/**
+ * An escape hatch for a DB-specific type with no portable meaning (PG `tsvector`, etc.). Carries
+ * the owning driver `db` so a schema authored for one DB can't silently typecheck against another.
+ * `params` carries the type's parameters for parameterized natives — `numeric(p,s)`, `varchar(n)`,
+ * `timestamp(p)` — so a driver round-trips `numeric(10,2)` exactly. Order matters; ignored when empty.
+ */
+ | {
+    t: "native";
+    db: string;
+    name: string;
+    params?: (string | number)[];
+};
+type GeometryKind = "feature" | "point" | "line" | "polygon" | "multipoint" | "multiline" | "multipolygon" | "collection";
+declare const scalar: (name: ScalarName) => PortableType;
+declare const literal: (value: string | number | boolean) => PortableType;
+/** `option<T>` — but `option<any>` collapses to `any` (any already admits NONE), matching ddl.ts. */
+declare const option: (inner: PortableType) => PortableType;
+/**
+ * `T | null` — with the fold rule `nullable(option(X))` -> `option(nullable(X))` so
+ * `.optional().nullable()` ≡ `.nullish()`, and `nullable(any)` collapses to `any`.
+ */
+declare const nullable: (inner: PortableType) => PortableType;
+declare const array: (elem: PortableType, size?: number) => PortableType;
+declare const union: (members: PortableType[]) => PortableType;
+declare const record: (tables: string[]) => PortableType;
+
+/** CRUD permissions — each a boolean (FULL/NONE) or a dialect WHERE-expression string (carried verbatim). */
+interface PortablePermissions {
+    select?: boolean | string;
+    create?: boolean | string;
+    update?: boolean | string;
+    delete?: boolean | string;
+}
+/** A field in the portable substrate: a structured {@link PortableType} + its dialect clauses (verbatim). */
+interface PortableField {
+    name: string;
+    type: PortableType;
+    flexible?: boolean;
+    readonly?: boolean;
+    default?: string;
+    default_always?: boolean;
+    value?: string;
+    computed?: string;
+    assert?: string;
+    /**
+     * A field-level CHECK constraint (dialect boolean expression, carried verbatim). DISTINCT from
+     * `assert`: that is Surreal's `ASSERT`; this is the SQL `CHECK` a driver like Postgres emits. A
+     * driver maps whichever of the two it supports and surfaces the other as a capability gap.
+     */
+    check?: string;
+    comment?: string;
+    /** Referential action(s) on a foreign reference. A driver honors the actions it supports. */
+    reference?: {
+        on_delete?: string;
+        on_update?: string;
+    };
+    /**
+     * Auto-generated identity column — `GENERATED ALWAYS`/`BY DEFAULT AS IDENTITY`; a `serial`/
+     * auto-increment column maps here too. Absent → an ordinary column. Drivers without identity ignore it.
+     */
+    identity?: "always" | "by-default";
+    permissions?: PortablePermissions;
+    table: string;
+}
+
+export { type GeometryKind, type PortableField, type PortablePermissions, type PortableType, type ScalarName, array, literal, nullable, option, record, scalar, union };

package/lib/driver.js

@@ -0,0 +1,47 @@
+import {
+  array,
+  connectionEntry,
+  literal,
+  nullable,
+  option,
+  record,
+  scalar,
+  union
+} from "./chunk-C4D6JWSE.js";
+import {
+  KindRegistry,
+  buildKindDiff,
+  driverNames,
+  emitKinds,
+  getDriver,
+  introspectKinds,
+  lowerSchema,
+  orderObjects,
+  planKinds,
+  registerDriver,
+  snapshotKinds,
+  snapshotObjects
+} from "./chunk-T23RNU7G.js";
+export {
+  KindRegistry,
+  array,
+  buildKindDiff,
+  connectionEntry,
+  driverNames,
+  emitKinds,
+  getDriver,
+  introspectKinds,
+  literal,
+  lowerSchema,
+  nullable,
+  option,
+  orderObjects,
+  planKinds,
+  record,
+  registerDriver,
+  scalar,
+  snapshotKinds,
+  snapshotObjects,
+  union
+};
+//# sourceMappingURL=driver.js.map

package/lib/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/lib/index.d.ts

@@ -0,0 +1,84 @@
+import { A as Authored, a as AuthoredDef } from './driver-Dh5hLKHm.js';
+export { T as ApplyOptions, U as ConnectionOverrides, a3 as Definable, c as Diff, d as DiffItem, D as Driver, H as EMPTY_STORED, W as EmitOptions, F as Filter, h as FilterOpts, a6 as KindDisplay, a7 as KindEngine, a8 as KindPlan, a9 as KindRegistry, aa as KindSnapshot, ab as KindSpec, L as LocalOnly, M as MergeOptions, y as MergeResult, J as Migration, Y as MigrationDirection, Z as MigrationRecord, _ as MigrationStore, ad as OrderNode, af as PortableObject, P as PullFilePlan, B as PullPlan, ah as Ref, C as RenderedUnit, R as ResolvedConfig, ai as ResolvedDisplay, a0 as ShadowCapability, a1 as Statement, S as StoredSnapshot, v as actionLabel, w as applyPull, a2 as buildKindDiff, G as checksum, V as driverNames, a4 as emitKinds, j as filterKinds, f as formatDiff, e as formatItems, g as formatPatch, X as getDriver, k as inCat, n as intersectKinds, a5 as introspectKinds, i as isEmptyDiff, o as kindFlags, x as lineDiff, I as listMigrations, l as loadConfig, b as loadProject, ac as lowerSchema, m as makeJiti, p as mergeStored, z as mergeUnits, ae as orderObjects, q as parseFilter, u as passesFilter, ag as planKinds, K as readSnapshot, $ as registerDriver, r as resolveConnectionConfig, N as slug, aj as snapshotKinds, ak as snapshotObjects, s as summarizeKinds, O as timestamp, t as tokenDiff, E as unifiedDiff, Q as writeSnapshot } from './driver-Dh5hLKHm.js';
+export { C as ConnectionConfigBase, a as ConnectionEntry, b as ConnectionInput, R as ResolveContext, d as ResolvedConnectionHandle, c as connectionEntry, i as isConnectionEntry } from './config-TIiKDd9t.js';
+export { PortableField, PortablePermissions, PortableType, ScalarName, array, literal, nullable, option, record, scalar, union } from './driver.js';
+import 'jiti';
+import 'commander';
+
+/**
+ * The diff pager, resolved the way git does: `pager.diff` → `core.pager` → `$GIT_PAGER` →
+ * `$PAGER`. So a user with `core.pager = delta` gets delta for free, with their own config.
+ */
+declare function resolvePager(): string | undefined;
+/** Pipe `text` through `pager` (a shell command, possibly with args); resolve when it exits. */
+declare function pipeThroughPager(pager: string, text: string): Promise<void>;
+
+/**
+ * The NEUTRAL view of a loaded table the engine reads — just `name` plus the `config.relation` flag
+ * used for ordering. A driver casts this to its own concrete table builder in `lower`. (The runtime
+ * object is the driver's real `TableDef`; the engine never names that type.)
+ */
+interface AnyTable extends Authored {
+    readonly config: {
+        readonly relation?: unknown;
+    };
+}
+/**
+ * Load every schema object from `schemaPath` (a single `.ts` module, or a directory of them): the
+ * tables/relations (ordered normal-before-relation, then by name, for stable DDL) and the standalone
+ * defs (`defineEvent`/`defineFunction`). One pass over the files.
+ */
+declare function loadDefs(schemaPath: string): Promise<{
+    tables: AnyTable[];
+    defs: AuthoredDef[];
+    /** Absolute source file each table/def was loaded from (for `diff`'s file annotations). */
+    fileOf: Map<AnyTable | AuthoredDef, string>;
+}>;
+/** The tables/relations from `schemaPath` (standalone events excluded — see {@link loadDefs}). */
+declare function loadSchemas(schemaPath: string): Promise<AnyTable[]>;
+/** A schema file's exported entities (tables/functions/accesses) and whether it holds ONLY those. */
+interface LocalFileEntities {
+    /** Each schema entity by its export-const identifier + its DB name (table/function/access name). */
+    entities: {
+        exportName: string;
+        name: string;
+        kind: "table" | "def";
+    }[];
+    /** True when EVERY runtime export of the file is a schema entity (no helpers / other exports). */
+    pureSchema: boolean;
+}
+/**
+ * Scan each schema file for the tables/functions/accesses it exports (by export-const name), and
+ * whether the file is purely schema. `pull` uses this to find whole-entity local-only schema
+ * (entities the live DB doesn't have) and to decide whether a file is safe to delete when mirroring
+ * the DB. Standalone events are not whole entities (they attach to a table), so they don't count as
+ * entities — a file exporting one is therefore not `pureSchema` and won't be auto-deleted.
+ */
+declare function scanLocalEntities(schemaPath: string): Promise<Map<string, LocalFileEntities>>;
+/** Map of table name → the file that defines it (for `pull`'s duplicate-definition check). */
+declare function existingTables(schemaPath: string): Promise<Map<string, string>>;
+/**
+ * Names defined in more than one place, mapped to the files that define them (a file repeats if it
+ * defines the same name twice). `loadSchemas` silently lets the last definition win, so this is how
+ * `doctor` surfaces the otherwise-invisible conflict.
+ */
+declare function duplicateTables(schemaPath: string): Promise<Map<string, string[]>>;
+
+/** Whether colored output is enabled (a TTY and `NO_COLOR` unset). */
+declare const colorEnabled: () => boolean;
+declare const style: {
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    cyan: (s: string) => string;
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+};
+/** A green ✓ success line. */
+declare const ok: (s: string) => string;
+/** A red ✗ failure line. */
+declare const fail: (s: string) => string;
+/** Pluralize `n thing` / `n things`. */
+declare const plural: (n: number, word: string) => string;
+
+export { type AnyTable, Authored, AuthoredDef, colorEnabled, duplicateTables, existingTables, fail, loadDefs, loadSchemas, ok, pipeThroughPager, plural, resolvePager, scanLocalEntities, style };