okmodel 0.0.0 → 0.1.0

package/dist/contracts/catalog/identifier.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Identifier rules and deterministic constraint and index names.
+ *
+ * Postgres stores 63 bytes (`NAMEDATALEN` minus the trailing NUL). A generated
+ * name that would be longer keeps a hash suffix so two long names stay distinct.
+ * The name is a function of a stable key, not of the field's current name, so
+ * renaming a field does not rename the constraint.
+ */
+import { utf8ByteLength } from "../utf8.js";
+/** Maximum Postgres identifier size in bytes. `NAMEDATALEN - 1`. */
+export declare const POSTGRES_IDENTIFIER_MAX_BYTES = 63;
+/** Why a constraint or index name is being generated. */
+export type NamePurpose = "primaryKey" | "unique" | "foreignKey" | "check" | "index";
+export { utf8ByteLength };
+/**
+ * Reports whether a name is an unquoted reserved word.
+ *
+ * Comparison is case-insensitive.
+ *
+ * @param name - Candidate identifier
+ * @returns `true` when Postgres would reject the unquoted word
+ */
+export declare function isReservedIdentifier(name: string): boolean;
+/**
+ * Rejects a name that fails the identifier rules.
+ *
+ * The rules are empty, NUL, other control characters, byte length, and an
+ * unquoted reserved word (OKM1122).
+ *
+ * @param name - Candidate identifier
+ * @param role - What the name refers to, used in the error
+ * @param limit - Dialect byte limit. Defaults to the Postgres limit
+ */
+export declare function assertIdentifier(name: string, role: string, limit?: number): void;
+/**
+ * Returns a name the dialect can store without truncating it.
+ *
+ * Names that already fit are unchanged, including reserved words (those are
+ * rejected by {@link assertIdentifier} before a name is stored). Longer names
+ * become a UTF-8 prefix, an underscore, and the first 8 hex characters of the
+ * SHA-256 of the original name.
+ *
+ * @param name - Requested identifier
+ * @param limit - Dialect byte limit. Defaults to the Postgres limit
+ * @returns The name to store
+ */
+export declare function fitIdentifier(name: string, limit?: number): string;
+/**
+ * Generates a constraint or index name.
+ *
+ * Primary keys are `{parent}_pkey`, so the column name is not part of the
+ * name. Other purposes are `{parent}_{nameKey}_{tag}`. `nameKey` is chosen
+ * once and kept; a later field rename must pass the same key. A result that
+ * exceeds `limit` is fitted with a hash suffix.
+ *
+ * @param input - Parent, purpose, stable key, and dialect limit
+ * @returns The name to store on the object
+ */
+export declare function deterministicName(input: {
+    readonly parent: string;
+    readonly purpose: NamePurpose;
+    readonly nameKey?: string;
+    readonly limit?: number;
+}): string;
+/**
+ * Rejects NUL and other control characters in text that is not an identifier.
+ *
+ * @param value - Text stored in a definition
+ * @param role - What the text refers to
+ */
+export declare function assertStoredText(value: string, role: string): void;

package/dist/contracts/catalog/identity.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Namespaces, identity keys, and tenant resolution.
+ *
+ * The identity key is canonical JSON, so key order and runtime do not change it.
+ * Resolving a template never rewrites the identity.
+ */
+import { type Json } from "./json.js";
+import type { Namespace, ObjectIdentity, ObjectKind, ObjectRef } from "./types.js";
+/**
+ * A concrete schema name.
+ *
+ * @param name - Schema name stored in the catalog
+ * @returns A namespace that is not a template
+ */
+export declare function staticNamespace(name: string): Namespace;
+/**
+ * A namespace template such as `tenant_{id}`.
+ *
+ * The pattern must contain `{id}`. Every other character is an identifier
+ * character. The pattern is stored as written.
+ *
+ * @param pattern - Pattern containing the `{id}` placeholder
+ * @returns A template namespace
+ */
+export declare function templateNamespace(pattern: string): Namespace;
+/**
+ * Rejects a namespace that cannot be stored.
+ *
+ * Static names follow the identifier rules. Templates must contain `{id}`.
+ *
+ * @param namespace - Namespace to check
+ */
+export declare function assertNamespace(namespace: Namespace): void;
+/**
+ * Resolves a namespace for one tenant id.
+ *
+ * Static namespaces return their name. Templates substitute `{id}`. A
+ * hyphenated UUID is written as 32 lowercase hex digits so the result can
+ * enter an identifier. The id must be that UUID or `[a-z0-9_]`.
+ *
+ * @param namespace - Logical namespace
+ * @param tenantId - Tenant id. Ignored for a static namespace
+ * @returns The schema name to use at execution time
+ */
+export declare function resolveNamespace(namespace: Namespace, tenantId?: string): string;
+/**
+ * Stable identity key.
+ *
+ * @param identity - Object identity
+ * @returns Canonical JSON of the identity
+ */
+export declare function identityKey(identity: ObjectIdentity): string;
+/**
+ * Reports whether the dialect length limit applies to a kind.
+ *
+ * Grants and default privileges use a structured key and are exempt (D119).
+ *
+ * @param kind - Object kind
+ * @returns `false` for grants and default privileges
+ */
+export declare function identifierLimitApplies(kind: ObjectKind): boolean;
+/**
+ * Short label for an identity, used in error messages.
+ *
+ * @param identity - Object identity
+ * @returns Kind and name
+ */
+export declare function identityLabel(identity: ObjectIdentity): string;
+/**
+ * Reports whether two parent refs are the same logical object.
+ *
+ * @param left - First ref
+ * @param right - Second ref
+ * @returns `true` when namespace and name match
+ */
+export declare function sameRef(left: ObjectRef, right: ObjectRef): boolean;
+/**
+ * Reports whether two namespaces are the same logical namespace.
+ *
+ * @param left - First namespace
+ * @param right - Second namespace
+ * @returns `true` when form and text match
+ */
+export declare function sameNamespace(left: Namespace, right: Namespace): boolean;
+/**
+ * Canonical JSON for an identity.
+ *
+ * @param identity - Object identity
+ * @returns JSON object
+ */
+export declare function identityToJson(identity: ObjectIdentity): Json;
+/**
+ * Canonical JSON for a namespace.
+ *
+ * @param namespace - Static or template namespace
+ * @returns JSON object
+ */
+export declare function namespaceToJson(namespace: Namespace): Json;

package/dist/contracts/catalog/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Catalog contract for the runtime entry: envelope, identity, and names.
+ *
+ * Document checks, serialisation, parsing, hashing, and dependency order live
+ * in `document.ts` and `order.ts`. They are tooling and are not re-exported
+ * from the package entry.
+ */
+export { BUILT_KINDS, CATALOG_VERSION, KIND_OPERATIONS, OBJECT_KINDS, OBJECT_OPERATIONS, OWNERS, type AnchoredIdentity, type BuiltKind, type Catalog, type CatalogEnvelope, type CatalogObject, type ColumnDefinition, type ColumnObject, type ConstraintDefinition, type ConstraintKind, type ConstraintObject, type DefaultPrivilegeIdentity, type DependencyEdge, type ExtensionIdentity, type FunctionIdentity, type GrantIdentity, type GrantObjectRef, type IndexDefinition, type IndexObject, type Namespace, type NamespaceIdentity, type ObjectIdentity, type ObjectKind, type ObjectOperation, type ObjectRef, type Owner, type PartitionMethod, type Provenance, type ReferentialAction, type RoleIdentity, type SequenceDefinition, type SequenceObject, type TableDefinition, type TableObject, type TypeDefinition, type TypeObject, } from "./types.js";
+export { assertNamespace, identityKey, identityLabel, identifierLimitApplies, resolveNamespace, sameNamespace, sameRef, staticNamespace, templateNamespace, } from "./identity.js";
+export { POSTGRES_IDENTIFIER_MAX_BYTES, assertIdentifier, deterministicName, fitIdentifier, isReservedIdentifier, utf8ByteLength, type NamePurpose, } from "./identifier.js";
+export { column, constraint, index, sequence, table, type ColumnInput, type ConstraintInput, type IndexInput, type SequenceInput, type TableInput, } from "./object.js";

package/dist/contracts/catalog/json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Canonical JSON.
+ *
+ * Object keys are sorted. Strings are ASCII-only escapes, so the same value
+ * produces the same bytes on every runtime. Arrays keep their order.
+ */
+/** JSON values the canonical encoder accepts. Numbers are safe integers. */
+export type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [key: string]: Json | undefined;
+};
+/**
+ * Encodes a value with object keys sorted at every level.
+ *
+ * @param value - JSON value
+ * @returns Canonical text
+ */
+export declare function canonicalJson(value: Json): string;

package/dist/contracts/catalog/object.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Factories for the built catalog kinds.
+ *
+ * Each factory stores ownership, a normalised definition, and dependency
+ * edges. Constraint and index names are generated from a stable key and then
+ * left alone.
+ */
+import { type ColumnObject, type ConstraintKind, type ConstraintObject, type DependencyEdge, type IndexObject, type Namespace, type ObjectIdentity, type ObjectRef, type Owner, type Provenance, type ReferentialAction, type SequenceDefinition, type SequenceObject, type TableDefinition, type TableObject } from "./types.js";
+/** Fields every factory accepts. */
+type CommonInput = {
+    readonly owner?: Owner;
+    readonly provenance: Provenance;
+    readonly dependencies?: readonly ObjectIdentity[];
+};
+/** Input for {@link table}. */
+export type TableInput = CommonInput & {
+    readonly namespace: Namespace;
+    readonly name: string;
+    readonly partition?: TableDefinition["partition"];
+};
+/** Input for {@link column}. */
+export type ColumnInput = CommonInput & {
+    readonly parent: ObjectRef;
+    readonly name: string;
+    readonly dataType: string;
+    readonly nullable: boolean;
+    readonly defaultExpression?: string;
+    readonly identity?: {
+        readonly always: boolean;
+    };
+    readonly generated?: {
+        readonly stored: boolean;
+        readonly expression: string;
+    };
+};
+/** Input for {@link index}. */
+export type IndexInput = CommonInput & {
+    readonly parent: ObjectRef;
+    readonly name?: string;
+    readonly nameKey?: string;
+    readonly columns?: readonly string[];
+    readonly unique?: boolean;
+    readonly predicate?: string;
+    readonly expression?: string;
+};
+/** Input for {@link constraint}. */
+export type ConstraintInput = CommonInput & {
+    readonly parent: ObjectRef;
+    readonly constraintKind: ConstraintKind;
+    readonly name?: string;
+    readonly nameKey?: string;
+    readonly columns?: readonly string[];
+    readonly expression?: string;
+    readonly references?: {
+        readonly parent: ObjectRef;
+        readonly columns: readonly string[];
+        readonly onDelete?: ReferentialAction;
+        readonly onUpdate?: ReferentialAction;
+    };
+    readonly deferrable?: boolean;
+    readonly initially?: "immediate" | "deferred";
+    readonly nullsNotDistinct?: boolean;
+};
+/** Input for {@link sequence}. */
+export type SequenceInput = CommonInput & {
+    readonly namespace: Namespace;
+    readonly name: string;
+    readonly dataType?: SequenceDefinition["dataType"];
+    readonly start?: string;
+    readonly increment?: string;
+    readonly cycle?: boolean;
+};
+/**
+ * Builds a table object.
+ *
+ * A partitioned table sets `partition`. Copied partition primary keys and
+ * inherited indexes are not created; they are not catalog objects.
+ *
+ * @param input - Name, namespace, ownership, and optional partition
+ * @returns A table envelope
+ */
+export declare function table(input: TableInput): TableObject;
+/**
+ * Builds a column object.
+ *
+ * The column depends on its parent table. Extra dependencies (a sequence, for
+ * example) are kept.
+ *
+ * @param input - Parent, name, type, and nullability
+ * @returns A column envelope
+ */
+export declare function column(input: ColumnInput): ColumnObject;
+/**
+ * Builds an index object.
+ *
+ * The stored name comes from {@link deterministicName} unless `name` is set.
+ * Either way a name past the dialect limit is fitted. `nameKey` is what a
+ * later rename must keep passing.
+ *
+ * @param input - Parent, columns, and the stable name key
+ * @returns An index envelope
+ */
+export declare function index(input: IndexInput): IndexObject;
+/**
+ * Builds a constraint object.
+ *
+ * Primary key names are `{parent}_pkey` and do not include column names.
+ * Other names use `nameKey`, which stays fixed when a field is renamed.
+ *
+ * @param input - Parent, kind, columns, and the stable name key
+ * @returns A constraint envelope
+ */
+export declare function constraint(input: ConstraintInput): ConstraintObject;
+/**
+ * Builds a sequence object.
+ *
+ * @param input - Namespace, name, and sequence counters
+ * @returns A sequence envelope
+ */
+export declare function sequence(input: SequenceInput): SequenceObject;
+/**
+ * Sorts and dedupes dependency targets.
+ *
+ * @param targets - Identity targets, structural ones first
+ * @returns Edges in identity-key order
+ */
+export declare function normaliseEdges(targets: readonly ObjectIdentity[]): readonly DependencyEdge[];
+/**
+ * Compares two strings by UTF-16 code unit, which is stable across runtimes.
+ *
+ * @param left - First string
+ * @param right - Second string
+ * @returns A negative, zero, or positive number
+ */
+export declare function compareText(left: string, right: string): number;
+/**
+ * Rejects a provenance that cannot be stored.
+ *
+ * @param provenance - Origin and name
+ */
+export declare function assertProvenance(provenance: Provenance): void;
+export {};

package/dist/contracts/catalog/order.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Dependency order.
+ *
+ * Create order is a topological order: dependencies first, ties broken by
+ * identity key. The comparison is UTF-16 code unit order, not a locale.
+ * Each object's identity key is computed once per pass.
+ */
+import type { CatalogObject } from "./types.js";
+/** One catalog object and the identity key computed for it. */
+export type IndexedObject = {
+    readonly key: string;
+    readonly object: CatalogObject;
+};
+/**
+ * Computes each object's identity key once.
+ *
+ * A duplicate identity is OKM1023.
+ *
+ * @param objects - Catalog objects
+ * @returns Objects paired with their keys, in input order
+ */
+export declare function indexObjects(objects: readonly CatalogObject[]): readonly IndexedObject[];
+/**
+ * Orders objects so each dependency appears before the object that needs it.
+ *
+ * A cycle is OKM1026. A self-edge, or a target that is not in `objects`, is
+ * OKM1020. A duplicate identity is OKM1023.
+ *
+ * @param objects - Catalog objects to order
+ * @returns Create order
+ */
+export declare function dependencyOrder(objects: readonly CatalogObject[]): readonly CatalogObject[];
+/**
+ * Topological order of objects whose identity keys are already known.
+ *
+ * A cycle is OKM1026. A self-edge, or a target that is not in `indexed`, is
+ * OKM1020.
+ * `indexed` must not contain duplicate keys.
+ *
+ * @param indexed - Objects paired with identity keys
+ * @returns Create order
+ */
+export declare function orderIndexed(indexed: readonly IndexedObject[]): readonly CatalogObject[];

package/dist/contracts/catalog/rewrite.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Rewrites an identifier inside stored expression text.
+ *
+ * Check expressions and index predicates are text (D128). A declared rename
+ * updates references in that text and leaves string literals alone.
+ */
+/**
+ * Replaces `from` with `to` outside single-quoted strings.
+ *
+ * Quoted identifiers (`"from"`) and bare words both change. A word inside a
+ * SQL string does not.
+ *
+ * @param text - Expression text
+ * @param from - Identifier to replace
+ * @param to - Replacement identifier
+ * @returns The expression, or the same string when nothing changed
+ */
+export declare function replaceIdentifier(text: string, from: string, to: string): string;