@sequenceholdings/orm 0.1.0 → 0.1.2

package/dist/authoring.d.ts

@@ -0,0 +1,274 @@
+import { ColumnType, CanonicalColumn, CanonicalDefinition } from './canonical.js';
+import 'zod';
+
+/**
+ * Fluent column builders for the v2 authoring surface — `t.uuid()`,
+ * `t.text().notNull().unique()`, `t.enum(status).default('open')`, …
+ *
+ * Builders carry plain serializable state and produce `CanonicalColumn` data
+ * (canonical definition v2). They never touch Drizzle: the server builds
+ * Drizzle entities from canonical JSON, consumer TypeScript never runs
+ * server-side (plan §2).
+ *
+ * Cross-copy safety: the jiti loader evaluates its own transpiled copy of
+ * this module, so identification uses the `kind` brand — never `instanceof`.
+ */
+
+declare const COLUMN_BRAND: "seq-column";
+declare const ENUM_BRAND: "seq-enum";
+/** A namespace-level Postgres enum, created with `defineEnum` (table.ts). */
+interface EnumRef {
+    readonly kind: typeof ENUM_BRAND;
+    readonly name: string;
+    readonly values: readonly string[];
+}
+declare function isEnumRef(value: unknown): value is EnumRef;
+/** The allowlisted SQL default functions — `.default('now()')` maps here, not to a literal. */
+declare const COLUMN_DEFAULT_FNS: readonly ["gen_random_uuid()", "now()"];
+type ColumnDefaultFn = (typeof COLUMN_DEFAULT_FNS)[number];
+type ColumnDefaultLiteral = string | number | boolean | null;
+type ColumnTypeSpec = ColumnType | {
+    readonly enum: string;
+};
+/** `authorSub` → `author_sub`, `authorURLPath` → `author_url_path`. */
+declare function deriveColumnName(propertyName: string): string;
+declare class ColumnBuilder {
+    readonly kind: "seq-column";
+    private readonly state;
+    constructor(type: ColumnTypeSpec, columnName?: string);
+    /** Marks this column as (part of) the primary key. Implies NOT NULL. */
+    primaryKey(): this;
+    notNull(): this;
+    unique(): this;
+    /**
+     * Column default: a literal, or one of the allowlisted SQL functions
+     * (`'gen_random_uuid()'` / `'now()'`), which serialize as `defaultFn`.
+     */
+    default(value: ColumnDefaultLiteral): this;
+    description(text: string): this;
+    /** Migration rename hint: the previous Postgres column name. */
+    renamedFrom(previousColumnName: string): this;
+    /** Migration cast hint: the `USING` SQL applied when this column changes type. */
+    cast(usingSql: string): this;
+    /** Emits `@deprecated` in the generated SDL; the column stays queryable. */
+    deprecated(): this;
+    /** Whether `.primaryKey()` was called — collected into the table-level PK. */
+    get isPrimaryKey(): boolean;
+    /** The enum name when this is an enum column, else undefined. */
+    get enumName(): string | undefined;
+    /** Postgres column name: explicit override, else snake_case of the property name. */
+    columnNameFor(propertyName: string): string;
+    /** Serialize to a canonical v2 column. Validation happens in serializeNamespace. */
+    toCanonicalColumn(propertyName: string): CanonicalColumn;
+}
+declare function isColumnBuilder(value: unknown): value is ColumnBuilder;
+/**
+ * The column-type factory. The optional argument overrides the derived
+ * snake_case Postgres column name: `t.text('legacy_name')`.
+ */
+declare const t: {
+    readonly uuid: (columnName?: string) => ColumnBuilder;
+    readonly text: (columnName?: string) => ColumnBuilder;
+    readonly integer: (columnName?: string) => ColumnBuilder;
+    readonly bigint: (columnName?: string) => ColumnBuilder;
+    readonly numeric: (columnName?: string) => ColumnBuilder;
+    readonly double: (columnName?: string) => ColumnBuilder;
+    readonly boolean: (columnName?: string) => ColumnBuilder;
+    readonly timestamptz: (columnName?: string) => ColumnBuilder;
+    readonly date: (columnName?: string) => ColumnBuilder;
+    readonly jsonb: (columnName?: string) => ColumnBuilder;
+    readonly enum: (ref: EnumRef, columnName?: string) => ColumnBuilder;
+};
+
+declare const TABLE_BRAND: "seq-table";
+declare const LINK_BRAND: "seq-link";
+/** A link target: the table itself, or a lazy thunk for forward/cyclic references. */
+type TableRef = SeqTable | (() => SeqTable);
+type LinkKind = 'toOne' | 'toMany' | 'toPlatformUser';
+interface SeqLink {
+    readonly kind: typeof LINK_BRAND;
+    readonly linkKind: LinkKind;
+    /** Absent for toPlatformUser — the platform-users view needs no target. */
+    readonly target: TableRef | undefined;
+    /** FK column (property or column name). toOne/toPlatformUser: on this table; toMany: on the target. */
+    readonly on: string;
+    readonly references: string | undefined;
+    readonly enforce: boolean;
+    readonly description: string | undefined;
+}
+interface ToOneOptions {
+    on: string;
+    references?: string;
+    /** Emit a real FK constraint (same-namespace toOne only). */
+    enforce?: boolean;
+    description?: string;
+}
+interface ToManyOptions {
+    on: string;
+    references?: string;
+    description?: string;
+}
+interface ToPlatformUserOptions {
+    /** Column on this table holding the platform user `sub` (or `references` override). */
+    on: string;
+    references?: string;
+    description?: string;
+}
+declare function toOne(target: TableRef, options: ToOneOptions): SeqLink;
+declare function toMany(target: TableRef, options: ToManyOptions): SeqLink;
+/** Link to the built-in read-only platform-users view (plan §4b) — no table definition needed. */
+declare function toPlatformUser(options: ToPlatformUserOptions): SeqLink;
+declare function isSeqLink(value: unknown): value is SeqLink;
+interface PolicyVariantInput {
+    /** Claims-only guard: `capability('x')` / `role('y')` / claim comparisons. */
+    when: string;
+    /** Exactly one of `allow: true` or `policy` (validated at serialize time). */
+    allow?: true;
+    policy?: string;
+}
+interface PolicyWithVariantsInput {
+    default: string;
+    variants?: readonly PolicyVariantInput[];
+}
+/** A policy: a DSL source string, or a default + per-role/capability variants (§4c). */
+type PolicyInput = string | PolicyWithVariantsInput;
+interface TablePoliciesInput {
+    read?: PolicyInput;
+    write?: PolicyInput;
+}
+interface IndexInput {
+    /** Property names (camelCase) or Postgres column names. */
+    columns: readonly string[];
+    unique?: boolean;
+    name?: string;
+}
+interface ActionParamInput {
+    type: ColumnType;
+    nullable?: boolean;
+}
+interface ActionInput {
+    name: string;
+    requires?: string;
+    params?: Record<string, ActionParamInput>;
+    executes: string;
+    returns?: 'rows' | 'rowsAffected' | 'scalar';
+    audit?: {
+        action: string;
+        resource: string;
+    };
+}
+interface TableConfig {
+    description?: string;
+    /** Table-level migration rename hint (new in v2). */
+    renamedFrom?: string;
+    /** Composite primary key: property names (or column names). Mutually exclusive with column-level `.primaryKey()`. */
+    primaryKey?: readonly string[];
+    indexes?: readonly IndexInput[];
+    links?: Record<string, SeqLink>;
+    policies?: TablePoliciesInput;
+    actions?: readonly ActionInput[];
+}
+interface SeqTable {
+    readonly kind: typeof TABLE_BRAND;
+    readonly tableName: string;
+    readonly columns: Readonly<Record<string, ColumnBuilder>>;
+    readonly config: TableConfig;
+    /** Synced reflected source (`gold.*`) — set only by defineSyncedTable. */
+    readonly source: string | undefined;
+    /** Consumer file that defined the table (set when loaded via loadNamespaceFromDir). */
+    readonly file: string | undefined;
+}
+declare function isSeqTable(value: unknown): value is SeqTable;
+declare function defineTable(name: string, columns: Record<string, ColumnBuilder>, config?: TableConfig): SeqTable;
+interface SyncedTableConfig {
+    /** Reflected read-only source, restricted to the gold layer: `gold.<table>`. */
+    source: string;
+    description?: string;
+}
+declare function defineSyncedTable(name: string, config: SyncedTableConfig): SeqTable;
+declare function defineEnum(name: string, values: readonly string[]): EnumRef;
+
+declare const NAMESPACE_CONFIG_BRAND: "seq-namespace-config";
+interface NamespaceCapabilitiesInput {
+    /** Verbatim custom-roles grammar (@sequenceholdings/custom-roles-manifest). */
+    roles?: unknown;
+    /** Org-level capability pins this namespace attaches to. */
+    uses?: readonly string[];
+}
+interface NamespaceConfigInput {
+    namespace: string;
+    description?: string;
+    capabilities?: NamespaceCapabilitiesInput;
+}
+interface SeqNamespaceConfig {
+    readonly kind: typeof NAMESPACE_CONFIG_BRAND;
+    readonly namespace: string;
+    readonly description: string | undefined;
+    readonly capabilities: NamespaceCapabilitiesInput;
+    readonly file: string | undefined;
+}
+declare function isSeqNamespaceConfig(value: unknown): value is SeqNamespaceConfig;
+declare function defineNamespace(input: NamespaceConfigInput): SeqNamespaceConfig;
+interface SerializeNamespaceInput {
+    config: SeqNamespaceConfig;
+    tables: readonly SeqTable[];
+    enums?: readonly EnumRef[];
+}
+/**
+ * Serialize the authored namespace to a validated, normalized
+ * `CanonicalDefinition` (definition_format: 2). Throws `OrmDefinitionError`
+ * naming the table/file on any inconsistency.
+ */
+declare function serializeNamespace(input: SerializeNamespaceInput): CanonicalDefinition;
+/** sha256 over the v1 hash domain + key-sorted JSON of the normalized canonical definition. */
+declare function computeCanonicalHash(definition: CanonicalDefinition): string;
+
+declare const NAMESPACE_CONFIG_FILE = "sequence.config.ts";
+declare const SCHEMA_DIR = "schema";
+interface LoadNamespaceOptions {
+    /**
+     * Test/dev hook: absolute path that bare `'@sequenceholdings/orm'` imports
+     * in consumer files resolve to (jiti alias). Leave unset in production —
+     * the consumer's own installed package resolves naturally.
+     */
+    ormModulePath?: string;
+}
+interface LoadedNamespaceV2 {
+    readonly canonical: CanonicalDefinition;
+    readonly hash: string;
+    /** Relative paths of the files that were imported, config first. */
+    readonly files: readonly string[];
+}
+declare function loadNamespaceFromDir(dir: string, options?: LoadNamespaceOptions): Promise<LoadedNamespaceV2>;
+
+/**
+ * Module-registry pattern for the authoring surface: `defineTable` /
+ * `defineEnum` / `defineNamespace` register into the ACTIVE collection
+ * context while `loadNamespaceFromDir` imports a consumer's files, so the
+ * loader collects definitions without inspecting module exports.
+ *
+ * The context stack lives on `globalThis` under a `Symbol.for` key — NOT in
+ * module scope — because the jiti loader evaluates its own transpiled copy of
+ * this module when a consumer file imports '@sequenceholdings/orm'. Both
+ * copies must observe the same registrations (the graphql-js dual-package
+ * discipline), so everything registered is plain data identified by `kind`
+ * brand strings, never `instanceof`.
+ */
+interface AuthoringRegistration {
+    readonly value: unknown;
+    readonly file: string | undefined;
+}
+interface AuthoringContext {
+    /** Set by the loader before importing each consumer file — error attribution. */
+    currentFile: string | undefined;
+    readonly tables: AuthoringRegistration[];
+    readonly enums: AuthoringRegistration[];
+    readonly configs: AuthoringRegistration[];
+}
+/** Push a fresh collection context; every define* call registers into it until ended. */
+declare function beginAuthoringContext(): AuthoringContext;
+/** Pop the context; throws if collection begin/end calls are mismatched (programmer error). */
+declare function endAuthoringContext(context: AuthoringContext): void;
+declare function activeAuthoringContext(): AuthoringContext | undefined;
+
+export { type ActionInput, type ActionParamInput, type AuthoringContext, type AuthoringRegistration, COLUMN_BRAND, COLUMN_DEFAULT_FNS, ColumnBuilder, type ColumnDefaultFn, type ColumnDefaultLiteral, type ColumnTypeSpec, ENUM_BRAND, type EnumRef, type IndexInput, LINK_BRAND, type LinkKind, type LoadNamespaceOptions, type LoadedNamespaceV2, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, type NamespaceCapabilitiesInput, type NamespaceConfigInput, type PolicyInput, type PolicyVariantInput, type PolicyWithVariantsInput, SCHEMA_DIR, type SeqLink, type SeqNamespaceConfig, type SeqTable, type SerializeNamespaceInput, type SyncedTableConfig, TABLE_BRAND, type TableConfig, type TablePoliciesInput, type TableRef, type ToManyOptions, type ToOneOptions, type ToPlatformUserOptions, activeAuthoringContext, beginAuthoringContext, computeCanonicalHash, defineEnum, defineNamespace, defineSyncedTable, defineTable, deriveColumnName, endAuthoringContext, isColumnBuilder, isEnumRef, isSeqLink, isSeqNamespaceConfig, isSeqTable, loadNamespaceFromDir, serializeNamespace, t, toMany, toOne, toPlatformUser };