@better-schemic/core 0.1.0-alpha.1

package/lib/driver.d.ts

@@ -0,0 +1,151 @@
+export { A as AnyConnectionEntry, d as ConnectionConfigBase, e as ConnectionEntry, f as ConnectionInput, h as ResolveContext, R as ResolvedConfig, k as StandardSchemaLike, l as connectionEntry } from './config-BYh7WA4P.js';
+export { b as ApplyOptions, A as Authored, a as AuthoredDef, c as CommandArgs, d as CommandContext, e as CommandIo, f as ConnectionOverrides, g as Definable, h as Diff, i as DiffItem, D as Driver, j as DriverCommand, k as EmitOptions, n as KindEngine, o as KindPlan, K as KindRegistry, p as KindSnapshot, q as KindSpec, t as MigrationDirection, u as MigrationRecord, v as MigrationStore, O as OrderNode, P as ParsedCommandArgs, w as PortableObject, R as Ref, S as ShadowCapability, G as Statement, N as buildKindDiff, T as driverNames, U as emitKinds, Z as getDriver, a0 as introspectKinds, a5 as lowerSchema, a8 as orderObjects, ab as planKinds, ad as registerDriver, af as snapshotKinds, ag as snapshotObjects } from './driver-LVldBEhS.js';
+import 'jiti';
+import './secrets-BETi5p8g.js';
+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 (a full-text vector type, 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 SQL driver 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-LC3VHUM2.js";
+import {
+  KindRegistry,
+  buildKindDiff,
+  driverNames,
+  emitKinds,
+  getDriver,
+  introspectKinds,
+  lowerSchema,
+  orderObjects,
+  planKinds,
+  registerDriver,
+  snapshotKinds,
+  snapshotObjects
+} from "./chunk-IUPOUD4L.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,154 @@
+import { B as BetterSchemicConfig, R as ResolvedConfig, A as AnyConnectionEntry } from './config-BYh7WA4P.js';
+export { a as BetterSchemicProject, C as ChainCtx, b as ChainableDriverFactory, c as ChainedConfig, d as ConnectionConfigBase, e as ConnectionEntry, f as ConnectionInput, E as EntryArgs, g as EntryClient, h as ResolveContext, i as ResolvedConnectionHandle, S as SchemicConfig, j as SchemicProject, k as StandardSchemaLike, l as connectionEntry, m as isConnectionEntry, n as loadConfig, o as loadProject, p as makeJiti, r as resolveConnectionConfig } from './config-BYh7WA4P.js';
+import { A as Authored, a as AuthoredDef } from './driver-LVldBEhS.js';
+export { b as ApplyOptions, C as CallableFunctions, c as CommandArgs, d as CommandContext, e as CommandIo, f as ConnectionOverrides, g as Definable, h as Diff, i as DiffItem, D as Driver, j as DriverCommand, E as EMPTY_STORED, k as EmitOptions, F as Filter, l as FilterOpts, m as KindDisplay, n as KindEngine, o as KindPlan, K as KindRegistry, p as KindSnapshot, q as KindSpec, L as LocalOnly, M as MergeOptions, r as MergeResult, s as Migration, t as MigrationDirection, u as MigrationRecord, v as MigrationStore, O as OrderNode, P as ParsedCommandArgs, w as PortableObject, x as PullFilePlan, y as PullPlan, R as Ref, z as RenderedUnit, B as ResolvedDisplay, S as ShadowCapability, G as Statement, H as StoredSnapshot, I as actionLabel, J as applyPull, N as buildKindDiff, Q as checksum, T as driverNames, U as emitKinds, V as filterKinds, W as formatDiff, X as formatItems, Y as formatPatch, Z as getDriver, _ as inCat, $ as intersectKinds, a0 as introspectKinds, a1 as isEmptyDiff, a2 as kindFlags, a3 as lineDiff, a4 as listMigrations, a5 as lowerSchema, a6 as mergeStored, a7 as mergeUnits, a8 as orderObjects, a9 as parseFilter, aa as passesFilter, ab as planKinds, ac as readSnapshot, ad as registerDriver, ae as slug, af as snapshotKinds, ag as snapshotObjects, ah as summarizeKinds, ai as timestamp, aj as tokenDiff, ak as unifiedDiff, al as writeSnapshot } from './driver-LVldBEhS.js';
+export { PortableField, PortablePermissions, PortableType, ScalarName, array, literal, nullable, option, record, scalar, union } from './driver.js';
+export { S as SecretProvider, a as SecretRef, e as env, b as envSecretProvider, i as isSecretRef, s as secret } from './secrets-BETi5p8g.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>;
+
+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 (any non-table `{ kind, name }` definable — the driver's registry owns the kinds). One pass.
+ */
+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;
+
+/**
+ * The neutral bound-client contract. A driver's client extends this and adds its typed query surface.
+ * It is an `AsyncDisposable`, so `await using db = await connect()` closes it at block exit.
+ *
+ * DISPOSE RULE (hard): a MANAGED client (opened by {@link resolveConnection} + the driver's `connect`)
+ * closes the connection it opened; a BYO client (wrapping the user's own pool) MUST make `close` a
+ * NO-OP — we never close a connection the user owns. The driver enforces this at construction.
+ */
+interface OrmClientBase extends AsyncDisposable {
+    /** Close the underlying connection (managed only; a BYO client is a no-op — see the dispose rule). */
+    close(): Promise<void>;
+}
+/** Mixin the default `[Symbol.asyncDispose]` (= `close`) onto a client class's prototype. */
+declare function asyncDisposable<T extends {
+    close(): Promise<void>;
+}>(proto: T): void;
+/** Options for {@link resolveConnection}: which connection, and where the config lives. */
+interface ResolveConnectionOptions {
+    /** Connection name; defaults to `defaultConnection`, else the sole connection, else `"default"`. */
+    name?: string;
+    /** Path to `better-schemic.config.ts` (else auto-discovered from `cwd`). */
+    config?: string;
+    /** Working directory to discover the config + resolve relative paths from. */
+    cwd?: string;
+    /** The resolver's typed args (its declared 2nd param) for a PARAMETERIZED connection. */
+    args?: unknown;
+}
+/**
+ * Resolve ONE named connection from the disk-discovered project config — the MANAGED path a driver's
+ * standalone `connect(name?)` uses before `driver.connect(config)`. Single-config or a teaching
+ * error (a bulk resolution must be arg-selected).
+ */
+declare function resolveConnection(opts?: ResolveConnectionOptions): Promise<ResolvedConfig>;
+/**
+ * The shared single-name resolution over an IN-MEMORY config: pick the entry (named /
+ * defaultConnection / sole / `"default"`), run the resolver with its typed `args`, and build one
+ * {@link ResolvedConfig} per returned config, each with a display label (config `key` > the entry's
+ * `label` hook > positional `name[i]`). Resolvers may query siblings via `ctx.connections` (lazy,
+ * cycle-checked; opened siblings are closed when resolution settles). Used by both
+ * {@link resolveConnection} (disk-discovered config) and {@link connectFromConfig} (`config.connect`).
+ */
+declare function resolveFromConfig(config: BetterSchemicConfig, root: string, opts?: {
+    name?: string;
+    args?: unknown;
+}): Promise<{
+    entry: AnyConnectionEntry;
+    name: string;
+    resolved: ResolvedConfig[];
+    labels: string[];
+}>;
+/**
+ * The runtime behind `config.connect(name, args?)` (see `defineConfig`): resolve the entry from the
+ * in-memory config and open its bound ORM client via the factory-embedded
+ * {@link AnyConnectionEntry.client} opener. The static return type is the entry's own client type
+ * (inferred per entry in `BetterSchemicProject`).
+ */
+declare function connectFromConfig(config: BetterSchemicConfig, name?: string, args?: unknown): Promise<unknown>;
+
+/**
+ * The context the seed runner hands to each seed as its second argument — a small filesystem helper
+ * scoped to the seed's own directory, so a seed can load supporting files (raw `.surql`/`.sql`, JSON,
+ * …) without an `import … with { type: "text" }` declaration or any `import.meta.url` path juggling.
+ *
+ * A driver types its `defineSeed(fn)` helper as `(db: Conn, ctx: SeedContext) => …`; the connection is
+ * the driver's own type, this context is dialect-neutral.
+ */
+interface SeedContext {
+    /** Absolute path of the directory containing the running seed. */
+    readonly dir: string;
+    /** Read a supporting file (resolved relative to {@link SeedContext.dir}) as a UTF-8 string. */
+    file(name: string): string;
+}
+
+export { AnyConnectionEntry, type AnyTable, Authored, AuthoredDef, BetterSchemicConfig, type OrmClientBase, type ResolveConnectionOptions, ResolvedConfig, type SeedContext, asyncDisposable, colorEnabled, connectFromConfig, duplicateTables, existingTables, fail, loadDefs, loadSchemas, ok, pipeThroughPager, plural, resolveConnection, resolveFromConfig, resolvePager, scanLocalEntities, style };