qubu 0.0.0 → 0.3.3

package/dist/json-CUZlv4HT.mjs

@@ -0,0 +1,169 @@
+//#region src/core/dialect.ts
+const standardCastTypes = {
+	integer: "INTEGER",
+	decimal: "DECIMAL",
+	text: "TEXT",
+	boolean: "BOOLEAN",
+	date: "DATE",
+	timestamp: "TIMESTAMP",
+	uuid: "UUID",
+	json: "JSON",
+	bigint: "BIGINT",
+	binary: "VARBINARY"
+};
+/** Resolve a logical or explicitly named CAST target for a dialect. */
+function resolveCastTarget(dialect, target) {
+	if (target.kind === "named-cast") return target.typeName;
+	return dialect.castTypes?.[target.type] ?? standardCastTypes[target.type];
+}
+const quoteIdentifier = (identifier) => `"${identifier.replaceAll("\"", "\"\"")}"`;
+function createDialect(options) {
+	return Object.freeze({
+		name: options.name,
+		quoteIdentifier: options.quoteIdentifier ?? quoteIdentifier,
+		placeholder: options.placeholder,
+		pagination: options.pagination,
+		rowLocking: options.rowLocking,
+		json: options.json,
+		castTypes: options.castTypes ? Object.freeze({ ...options.castTypes }) : void 0,
+		renderSchemaLiteral: options.renderSchemaLiteral,
+		explain: options.explain,
+		capabilities: Object.freeze([...options.capabilities ?? [], ...options.json ? ["json"] : []])
+	});
+}
+/**
+* Check a capability at runtime for callers that intentionally bypass the
+* typed render boundary or use a dialect supplied by an older integration.
+*/
+function assertDialectCapability(dialect, capability) {
+	if (dialect.capabilities?.includes(capability)) return;
+	throw new Error(`Dialect "${dialect.name}" does not support the "${capability}" capability`);
+}
+//#endregion
+//#region src/dialects/json.ts
+function jsonPath(path) {
+	return path.reduce((result, segment) => typeof segment === "number" ? `${result}[${segment}]` : `${result}.${JSON.stringify(segment)}`, "$");
+}
+function appendPath(context, path, requiredType) {
+	context.append("'");
+	context.append(jsonPath(path).replaceAll("'", "''"));
+	if (requiredType) {
+		const type = requiredType === "text" ? "string" : requiredType;
+		context.append(` ? (@.type() == "${type}")`);
+	}
+	context.append("'");
+}
+function renderSqlJsonValue(context, document, path, returning, requiredType) {
+	context.append("JSON_VALUE(");
+	context.render(document);
+	context.append(", ");
+	appendPath(context, path, requiredType);
+	context.append(` RETURNING ${returning} NULL ON EMPTY NULL ON ERROR)`);
+}
+const standardJson = {
+	renderScalar(context, document, path, kind) {
+		renderSqlJsonValue(context, document, path, kind === "text" ? "VARCHAR(512)" : kind === "number" ? "DOUBLE PRECISION" : "BOOLEAN", kind);
+	},
+	renderExists(context, document, path) {
+		context.append("COALESCE(JSON_EXISTS(");
+		context.render(document);
+		context.append(", ");
+		appendPath(context, path);
+		context.append(" FALSE ON ERROR), FALSE)");
+	}
+};
+function renderPostgresTarget(context, document, path) {
+	context.append("jsonb_path_query_first(CAST(");
+	context.render(document);
+	context.append(" AS JSONB), ");
+	appendPath(context, path);
+	context.append(")");
+}
+function postgresType(kind) {
+	return kind === "text" ? "string" : kind;
+}
+const postgresJson = {
+	renderScalar(context, document, path, kind) {
+		context.append("(CASE jsonb_typeof(");
+		renderPostgresTarget(context, document, path);
+		context.append(`) WHEN '${postgresType(kind)}' THEN `);
+		if (kind !== "text") context.append("CAST(");
+		context.append("(");
+		renderPostgresTarget(context, document, path);
+		context.append(" #>> '{}')");
+		if (kind !== "text") context.append(kind === "number" ? " AS DOUBLE PRECISION)" : " AS BOOLEAN)");
+		context.append(" END)");
+	},
+	renderExists(context, document, path) {
+		context.append("COALESCE(jsonb_path_exists(CAST(");
+		context.render(document);
+		context.append(" AS JSONB), ");
+		appendPath(context, path);
+		context.append(", '{}'::JSONB, TRUE), FALSE)");
+	}
+};
+function renderMySqlExtract(context, document, path) {
+	context.append("JSON_EXTRACT(");
+	context.render(document);
+	context.append(", ");
+	appendPath(context, path);
+	context.append(")");
+}
+function mysqlType(kind) {
+	return kind === "text" ? "STRING" : kind === "number" ? "INTEGER" : "BOOLEAN";
+}
+const mysqlJson = {
+	renderScalar(context, document, path, kind) {
+		context.append("(CASE JSON_TYPE(");
+		renderMySqlExtract(context, document, path);
+		context.append(`) WHEN '${mysqlType(kind)}' THEN `);
+		if (kind === "boolean") context.append("(");
+		renderSqlJsonValue(context, document, path, kind === "text" ? "CHAR" : kind === "number" ? "DOUBLE" : "CHAR");
+		if (kind === "boolean") context.append(" = 'true')");
+		context.append(" END)");
+	},
+	renderExists(context, document, path) {
+		context.append("COALESCE(JSON_CONTAINS_PATH(");
+		context.render(document);
+		context.append(", 'one', ");
+		appendPath(context, path);
+		context.append("), FALSE)");
+	}
+};
+function renderSqliteExtract(context, document, path) {
+	context.append("json_extract(");
+	context.render(document);
+	context.append(", ");
+	appendPath(context, path);
+	context.append(")");
+}
+function renderSqliteType(context, document, path) {
+	context.append("json_type(");
+	context.render(document);
+	context.append(", ");
+	appendPath(context, path);
+	context.append(")");
+}
+const sqliteJson = {
+	renderScalar(context, document, path, kind) {
+		context.append("(CASE ");
+		renderSqliteType(context, document, path);
+		if (kind === "text") {
+			context.append(" WHEN 'text' THEN ");
+			renderSqliteExtract(context, document, path);
+		} else if (kind === "number") {
+			context.append(" WHEN 'integer' THEN ");
+			renderSqliteExtract(context, document, path);
+			context.append(" WHEN 'real' THEN ");
+			renderSqliteExtract(context, document, path);
+		} else context.append(" WHEN 'true' THEN TRUE WHEN 'false' THEN FALSE");
+		context.append(" END)");
+	},
+	renderExists(context, document, path) {
+		context.append("(");
+		renderSqliteType(context, document, path);
+		context.append(" IS NOT NULL)");
+	}
+};
+//#endregion
+export { assertDialectCapability as a, standardJson as i, postgresJson as n, createDialect as o, sqliteJson as r, resolveCastTarget as s, mysqlJson as t };

package/dist/migration.d.mts

@@ -0,0 +1,215 @@
+import { T as SnapshotJsonValue, m as SnapshotDialect } from "./types-4Q076HKo.mjs";
+import { S as SnapshotDiffPath, _ as SnapshotDiffObjectKind, b as SnapshotDiffOperationType, f as SnapshotDiffDiagnostic, g as SnapshotDiffObject, m as SnapshotDiffEvidence, u as SnapshotDiff } from "./index-Dug5HnLB.mjs";
+//#region src/migration/types.d.ts
+/** The versioned envelope tag for dialect-neutral migration plans. */
+declare const migrationPlanFormat: "qubu-migration-plan";
+/** The first strict migration-plan format version. */
+declare const migrationPlanVersion: 1;
+/** Safety classifications carried by every planned operation. */
+type MigrationSafety = 'safe' | 'review-required' | 'destructive' | 'unsupported' | 'unknown';
+/** Lock strength required by a planned operation. */
+type MigrationLockRequirement = 'none' | 'shared' | 'exclusive' | 'unknown';
+/** Transaction behavior required by a planned operation. */
+type MigrationTransactionRequirement = 'required' | 'optional' | 'forbidden' | 'unknown';
+/** Operations that can appear in a migration plan. */
+type MigrationOperationType = 'add' | 'remove' | 'property-change' | 'physical-rename' | 'custom-sql';
+/** A condition a later executor must check before applying an operation. */
+type MigrationPreconditionType = 'snapshot-digest' | 'object-present' | 'object-absent' | 'property-equals';
+/** An immutable, serializable migration precondition. */
+interface MigrationPrecondition {
+  readonly type: MigrationPreconditionType;
+  readonly path: SnapshotDiffPath;
+  readonly kind: SnapshotDiffObjectKind | 'custom-sql';
+  readonly namespace?: string;
+  readonly logicalId?: string;
+  readonly physicalName?: string;
+  readonly digest?: string;
+  readonly property?: SnapshotDiffPath;
+  readonly value?: SnapshotJsonValue;
+}
+/** The explicit custom SQL escape hatch for one planned operation. */
+interface MigrationCustomSql {
+  readonly sql: string;
+  readonly dialect: SnapshotDialect;
+  readonly safety: MigrationSafety;
+  readonly position: number;
+  readonly reason: string;
+  readonly reversible: boolean;
+}
+/** Input accepted when attaching explicit custom SQL to a plan. */
+interface MigrationCustomSqlInput {
+  readonly sql: string;
+  readonly dialect: SnapshotDialect;
+  readonly safety: MigrationSafety;
+  readonly reason: string;
+  readonly reversible?: boolean;
+  /** Target an operation by deterministic ID when it already exists. */
+  readonly operationId?: string;
+  /** Or target a diff object by kind, namespace, and path. */
+  readonly kind?: SnapshotDiffObjectKind;
+  readonly namespace?: string;
+  readonly path?: SnapshotDiffPath;
+  /** Explicit dependency position. It does not render or execute SQL. */
+  readonly position?: number;
+  readonly dependsOn?: readonly string[];
+}
+/** A user's explicit decision for an unsafe or incomplete fact. */
+interface MigrationDecision {
+  readonly action: 'allow' | 'skip';
+  readonly reason: string;
+  readonly operationId?: string;
+  readonly kind?: SnapshotDiffObjectKind;
+  readonly namespace?: string;
+  readonly path?: SnapshotDiffPath;
+  readonly code?: MigrationDiagnosticCode;
+}
+/** Why a plan was blocked or needs review. */
+type MigrationDiagnosticCode = 'decision-required' | 'dependency-cycle' | 'invalid-plan' | 'unknown' | 'lossy' | 'unsupported' | 'destructive' | 'ambiguous' | 'custom-sql' | 'dialect-mismatch' | 'non-canonical';
+/** A structured plan diagnostic that keeps source diff context. */
+interface MigrationDiagnostic {
+  readonly code: MigrationDiagnosticCode;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly path: SnapshotDiffPath;
+  readonly operationId?: string;
+  readonly kind?: SnapshotDiffObjectKind | 'custom-sql';
+  readonly namespace?: string;
+  readonly logicalId?: string;
+  readonly physicalName?: string;
+  readonly dialect?: SnapshotDialect;
+  readonly evidence?: readonly SnapshotDiffEvidence[];
+  readonly source?: SnapshotDiffDiagnostic;
+}
+/** The source facts preserved on each non-custom migration operation. */
+interface MigrationOperationOrigin {
+  readonly type: SnapshotDiffOperationType;
+  readonly kind: SnapshotDiffObjectKind;
+  readonly namespace?: string;
+  readonly path: SnapshotDiffPath;
+  readonly logicalId?: string;
+  readonly physicalName?: string;
+  readonly physicalReference?: SnapshotJsonValue;
+  readonly provenance?: SnapshotJsonValue;
+  readonly before?: SnapshotDiffObject;
+  readonly after?: SnapshotDiffObject;
+  readonly evidence: readonly SnapshotDiffEvidence[];
+}
+/** One immutable operation in a migration plan. */
+interface MigrationOperation {
+  readonly id: string;
+  readonly type: MigrationOperationType;
+  readonly kind: SnapshotDiffObjectKind | 'custom-sql';
+  readonly objectKind: SnapshotDiffObjectKind | 'custom-sql';
+  readonly namespace?: string;
+  readonly path: SnapshotDiffPath;
+  readonly logicalId?: string;
+  readonly physicalName?: string;
+  readonly physicalReference?: SnapshotJsonValue;
+  readonly provenance?: SnapshotJsonValue;
+  readonly dialect: SnapshotDialect;
+  readonly safety: MigrationSafety;
+  readonly lock: MigrationLockRequirement;
+  readonly transaction: MigrationTransactionRequirement;
+  readonly reversible: boolean;
+  readonly reversibility: 'reversible' | 'irreversible';
+  readonly irreversibleReason?: string;
+  readonly preconditions: readonly MigrationPrecondition[];
+  readonly dependsOn: readonly string[];
+  readonly evidence: readonly SnapshotDiffEvidence[];
+  readonly origin?: MigrationOperationOrigin;
+  readonly customSql?: MigrationCustomSql;
+  readonly decision?: MigrationDecision;
+  readonly status: 'approved' | 'decision-required' | 'skipped';
+  readonly position: number;
+}
+/** A dependency edge. `from` must appear before `to`. */
+interface MigrationDependency {
+  readonly from: string;
+  readonly to: string;
+  readonly reason: 'parent-before-child' | 'child-before-parent' | 'reference-before-dependent' | 'explicit-custom-sql';
+}
+/** Immutable migration plan data. It contains no executor or SQL renderer. */
+interface MigrationPlan {
+  readonly format: typeof migrationPlanFormat;
+  readonly version: typeof migrationPlanVersion;
+  readonly dialect: SnapshotDialect;
+  readonly beforeDigest?: string;
+  readonly afterDigest?: string;
+  readonly safety: MigrationSafety;
+  readonly ready: boolean;
+  readonly operations: readonly MigrationOperation[];
+  readonly dependencies: readonly MigrationDependency[];
+  readonly decisions: readonly MigrationDecision[];
+  readonly diagnostics: readonly MigrationDiagnostic[];
+}
+/** Options for converting a resolved diff into a migration plan. */
+interface MigrationPlanOptions {
+  readonly decisions?: readonly MigrationDecision[];
+  readonly customSql?: readonly MigrationCustomSqlInput[];
+  readonly allowUnknown?: boolean;
+  readonly allowLossy?: boolean;
+  readonly allowUnsupported?: boolean;
+  readonly allowDestructive?: boolean;
+  readonly allowReviewRequired?: boolean;
+}
+/** A plan result retains a blocked plan so callers can inspect and review it. */
+type MigrationPlanResult = {
+  readonly ok: true;
+  readonly plan: MigrationPlan;
+  readonly diagnostics: readonly MigrationDiagnostic[];
+} | {
+  readonly ok: false;
+  readonly plan: MigrationPlan;
+  readonly diagnostics: readonly MigrationDiagnostic[];
+};
+/** Result returned by strict plan decoding. */
+type MigrationPlanDecodeResult = {
+  readonly ok: true;
+  readonly value: MigrationPlan;
+} | {
+  readonly ok: false;
+  readonly diagnostics: readonly MigrationDiagnostic[];
+};
+/** Result returned by non-throwing plan validation. */
+type MigrationPlanValidationResult = MigrationPlanDecodeResult;
+/** A validation error raised by throwing plan APIs. */
+declare class MigrationPlanValidationError extends TypeError {
+  readonly name = "MigrationPlanValidationError";
+  readonly diagnostics: readonly MigrationDiagnostic[];
+  readonly issues: readonly MigrationDiagnostic[];
+  constructor(diagnostics: readonly MigrationDiagnostic[]);
+}
+//#endregion
+//#region src/migration/plan.d.ts
+/**
+ * Convert a resolved SnapshotDiff into an immutable migration plan.
+ *
+ * This function only describes operations. It does not render SQL, open a
+ * connection, execute a transaction, or infer SQL from opaque snapshot data.
+ * A plan that still needs a safety decision is returned with `ok: false` so it
+ * can be reviewed without being mistaken for an executable plan.
+ */
+declare function createMigrationPlan(diff: SnapshotDiff, options?: MigrationPlanOptions): MigrationPlanResult;
+/** Alias for callers that treat plan creation as the main migration action. */
+declare const planMigration: typeof createMigrationPlan;
+declare const createPlan: typeof createMigrationPlan;
+/** Build a plan or throw one structured validation error when it is blocked. */
+declare function assertMigrationPlanFromDiff(diff: SnapshotDiff, options?: MigrationPlanOptions): MigrationPlan;
+/** Return a fixed-order immutable plan after strict validation. */
+declare function canonicalizeMigrationPlan(input: MigrationPlan): MigrationPlan;
+/** Encode a validated plan as deterministic JSON. */
+declare function encodeMigrationPlan(input: MigrationPlan): string;
+/** Decode and strictly validate a migration-plan JSON value. */
+declare function decodeMigrationPlan(input: string | unknown): MigrationPlanDecodeResult;
+/** Validate a plan without throwing. */
+declare function validateMigrationPlan(input: unknown): MigrationPlanValidationResult;
+/** Validate a plan and throw one structured error on failure. */
+declare function assertMigrationPlan(input: unknown): MigrationPlan;
+/** Compute a deterministic digest for cache keys and fixture assertions. */
+declare function migrationPlanDigest(input: MigrationPlan | string): string;
+declare const encodePlan: typeof encodeMigrationPlan;
+declare const decodePlan: typeof decodeMigrationPlan;
+declare const assertPlan: typeof assertMigrationPlan;
+declare const digestMigrationPlan: typeof migrationPlanDigest;
+//#endregion
+export { MigrationCustomSql, MigrationCustomSqlInput, MigrationDecision, MigrationDependency, MigrationDiagnostic, MigrationDiagnosticCode, MigrationLockRequirement, MigrationOperation, MigrationOperationOrigin, MigrationOperationType, MigrationPlan, MigrationPlanDecodeResult, MigrationPlanOptions, MigrationPlanResult, MigrationPlanValidationError, MigrationPlanValidationResult, MigrationPrecondition, MigrationPreconditionType, MigrationSafety, MigrationTransactionRequirement, type SnapshotDiff, assertMigrationPlan, assertMigrationPlanFromDiff, assertPlan, canonicalizeMigrationPlan, createMigrationPlan, createPlan, decodeMigrationPlan, decodePlan, digestMigrationPlan, encodeMigrationPlan, encodePlan, migrationPlanDigest, migrationPlanFormat, migrationPlanVersion, planMigration, validateMigrationPlan };