qubu 0.5.1 → 0.6.1

package/README.md

@@ -0,0 +1,112 @@
+# Qubu
+
+> Build parameterized SQL from simple type declarations and composable values.
+
+Qubu is a functional-first, type-aware SQL builder for TypeScript. Define
+tables once, combine expressions and clauses as ordinary values, and inspect
+the exact SQL and parameters before execution.
+
+Qubu stays close to SQL rather than replacing it with an object model. The type
+system tracks the facts needed to compose a query safely, while the rendered
+statement remains recognizable to anyone who knows SQL.
+
+> [!IMPORTANT]
+> Qubu is pre-alpha. Its public APIs and package structure may change between
+> releases.
+
+## A small query
+
+Declare a table, build a reusable condition, and pass it into a query:
+
+```ts
+import { eq, from, integer, render, select, table, text, where } from "qubu"
+
+const users = table("users", {
+  id: integer(),
+  name: text(),
+})
+
+const byId = where(eq(users.id, 7))
+
+const query = select(
+  {
+    id: users.id,
+    name: users.name,
+  },
+  from(users),
+  byId,
+)
+
+type UserRow = typeof query.row
+// { id: number; name: string }
+
+render(query)
+// {
+//   text: 'SELECT "users"."id" AS "id", "users"."name" AS "name" FROM "users" WHERE ("users"."id" = ?)',
+//   parameters: [7],
+// }
+```
+
+The table declaration supplies the application types, the condition remains a
+value that can be reused, and `7` becomes a bound parameter instead of SQL
+text. The projection determines the inferred result row.
+
+Clauses are independent values. `select()` accepts them in any argument order
+and renders them in canonical SQL order. Writing the final call in SQL order is
+still the preferred style because it is easier to scan.
+
+## Designed to be understood
+
+Qubu favors small declarations and functions that return composable values. A
+query can be assembled or changed one piece at a time, and TypeScript reports
+when those pieces do not fit. Rendering provides the SQL and parameters needed
+to check the result directly.
+
+These properties also help coding agents. A table declaration gives an agent a
+compact description of the data, composable values keep changes local, and the
+type checker and rendered SQL provide concrete feedback. That reduces guessing
+and makes the resulting work easier for a person to review.
+
+Qubu ships [version-matched documentation](docs/index.md) and a
+[Qubu skill](skills/qubu/SKILL.md) that routes agent tasks to the relevant
+guide for the installed package.
+
+## Scope and boundaries
+
+Qubu is for developers who know SQL and want composition and type checking
+without adopting an ORM model. It does not provide relationship loading,
+identity maps, lazy loading, or change tracking.
+
+Qubu constructs and renders queries, and it can pass them through an
+application-supplied adapter. The application continues to own its database
+driver, connections, and database lifecycle. PostgreSQL, SQLite, and MySQL
+differences remain visible through explicit dialect entrypoints.
+
+Optional entrypoints and workspace packages cover schema introspection, source
+generation, snapshots, diffs, migration planning, DDL emission, and migration
+operations. These stages remain separate so applications can inspect and
+approve a change before executing it. See [Supported features](docs/reference/supported-surface.md)
+for the complete package and ownership map.
+
+## Start here
+
+Install Qubu in a TypeScript project:
+
+```bash
+pnpm add qubu
+```
+
+Continue with the documentation for the task at hand:
+
+- [Getting started](docs/getting-started.md) defines a table and renders the
+  first query.
+- [Build a `SELECT`](docs/guides/select/overview.md) covers projections,
+  predicates, joins, grouping, and pagination.
+- [Write mutations](docs/guides/mutations.md) covers typed `INSERT`, `UPDATE`,
+  and `DELETE` statements.
+- [Dialects and execution](docs/dialects-and-execution.md) explains rendering
+  policies and the application-owned adapter boundary.
+- [Schema and migration documentation](docs/schema/tables-and-names.md) starts
+  with table metadata and links through snapshots, diffs, plans, and DDL.
+- [Troubleshooting](docs/troubleshooting.md) starts from common query failures
+  and their repair paths.

package/dist/codegen.d.mts

@@ -1,4 +1,4 @@
-import { St as IntrospectionDiagnostic, dt as IntrospectionResult, i as CatalogClassificationConfidence, p as CatalogDialect, z as CatalogPortableStorageType } from "./types-CTCqtFlS.mjs";
+import { St as IntrospectionDiagnostic, dt as IntrospectionResult, i as CatalogClassificationConfidence, p as CatalogDialect, z as CatalogPortableStorageType } from "./types-BEn0N_al.mjs";
 //#region src/codegen/types.d.ts
 /** TypeScript value types that the controlled source printer can emit. */
 type CodegenApplicationType = "unknown" | "string" | "number" | "boolean" | "bigint" | "Date" | "Uint8Array";

package/dist/codegen.mjs

@@ -1,5 +1,5 @@
 import { l as decodeSchemaSnapshot } from "./canonical-DMvR9yBe.mjs";
-import { t as mapCatalogToSnapshot } from "./snapshot-BSraiLtH.mjs";
+import { t as mapCatalogToSnapshot } from "./snapshot-DgsOhf_8.mjs";
 //#region src/codegen/source.ts
 const header = `/* Generated by Qubu. Do not edit this machine-owned file. */
 import * as _qubu from 'qubu'

package/dist/column-BzN8KFJa.mjs

@@ -0,0 +1,364 @@
+import { a as assertDialectCapability, i as standardJson, o as createDialect } from "./json-Db7XRD91.mjs";
+//#region src/dialects/standard.ts
+/** SQL:2008-style rendering defaults used by the core builder. */
+function standardDialect() {
+	return createDialect({
+		name: "standard-sql",
+		placeholder: () => "?",
+		json: standardJson
+	});
+}
+//#endregion
+//#region src/result.ts
+const resultValueMetadata = Symbol("qubu.result-value-metadata");
+function resultValue(type, decoder) {
+	return type === void 0 && decoder === void 0 ? void 0 : Object.freeze({
+		...type === void 0 ? {} : { type },
+		...decoder === void 0 ? {} : { decoder }
+	});
+}
+function resultValueOf(value) {
+	if (typeof value !== "object" || value === null) return;
+	return value[resultValueMetadata];
+}
+function attachResultValue(value, metadata) {
+	if (metadata === void 0) return value;
+	return Object.freeze({
+		...value,
+		[resultValueMetadata]: metadata
+	});
+}
+function createResultShape(fields) {
+	return Object.freeze({ fields: Object.freeze(fields.map((field) => Object.freeze({ ...field }))) });
+}
+function resultShapeValue(shape, name) {
+	const field = shape.fields.find((candidate) => candidate.name === name);
+	return field === void 0 ? void 0 : resultValue(field.type, field.decoder);
+}
+/** Decode SQLite/MySQL-style boolean values while accepting native booleans. */
+const booleanResultDecoder = (value) => {
+	if (typeof value === "boolean") return value;
+	if (value === 0 || value === 0n) return false;
+	if (value === 1 || value === 1n) return true;
+	throw new TypeError("Expected a boolean or numeric 0/1 result");
+};
+/** Decode a SQL DATE string as a JavaScript Date at UTC midnight. */
+const dateResultDecoder = (value) => {
+	if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
+	if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/u.test(value)) throw new TypeError("Expected a valid Date or YYYY-MM-DD result");
+	const decoded = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+	if (Number.isNaN(decoded.getTime()) || decoded.toISOString().slice(0, 10) !== value) throw new TypeError("Expected a valid calendar date result");
+	return decoded;
+};
+/** Decode a SQL/ISO timestamp string while accepting driver-created Dates. */
+const timestampResultDecoder = (value) => {
+	if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
+	if (typeof value !== "string") throw new TypeError("Expected a valid Date or timestamp string result");
+	const normalized = value.includes("T") ? value : value.replace(" ", "T");
+	const decoded = new Date(/(?:Z|[+-]\d{2}:?\d{2})$/u.test(normalized) ? normalized : `${normalized}Z`);
+	if (Number.isNaN(decoded.getTime())) throw new TypeError("Expected a valid timestamp result");
+	return decoded;
+};
+/** Decode a serialized JSON result. Use only when the adapter returns JSON text. */
+const jsonTextResultDecoder = (value) => {
+	if (typeof value !== "string") return value;
+	return JSON.parse(value);
+};
+/** Error raised when a projected driver value cannot be decoded. */
+var ResultDecodingError = class extends TypeError {
+	name = "ResultDecodingError";
+	field;
+	rowIndex;
+	resultType;
+	constructor(field, rowIndex, resultType) {
+		super(`Could not decode result field "${field}" in row ${rowIndex}${resultType === void 0 ? "" : ` as ${resultType}`}`);
+		this.field = field;
+		this.rowIndex = rowIndex;
+		this.resultType = resultType;
+	}
+};
+function decodeResultRow(row, shape, decoders, dialect, rowIndex) {
+	let decoded;
+	for (const field of shape.fields) {
+		const decoder = field.decoder ?? (field.type ? decoders?.[field.type] : void 0);
+		if (decoder === void 0 || row[field.name] === null) continue;
+		try {
+			decoded ??= { ...row };
+			decoded[field.name] = decoder(row[field.name], {
+				dialect,
+				field: field.name,
+				rowIndex
+			});
+		} catch {
+			throw new ResultDecodingError(field.name, rowIndex, field.type);
+		}
+	}
+	return decoded ?? row;
+}
+//#endregion
+//#region src/core/fragment.ts
+function fragment(render) {
+	return Object.freeze({ render });
+}
+function sequence(parts, separator = " ") {
+	return fragment((context) => {
+		let first = true;
+		for (const part of parts) {
+			if (!first) context.append(separator);
+			context.render(part);
+			first = false;
+		}
+	});
+}
+function parenthesize(part) {
+	return fragment((context) => {
+		context.append("(");
+		context.render(part);
+		context.append(")");
+	});
+}
+function isFragment(value) {
+	return typeof value === "object" && value !== null && "render" in value && typeof value.render === "function";
+}
+//#endregion
+//#region src/expressions/types.ts
+/** Runtime/type-level proof that an expression is safe to use in schema SQL. */
+const schemaExpressionBrand = Symbol("qubu.schema-expression");
+/** Add a concrete dialect requirement without dropping expression metadata. */
+function withDialectCapability(expression, capability) {
+	const wrapped = makeExpression(expression.expressionKind, (context) => {
+		assertDialectCapability(context.dialect, capability);
+		context.render(expression);
+	}, expression.expressionCategory, resultValueOf(expression));
+	return isSchemaExpression(expression) ? markSchemaExpression(wrapped) : wrapped;
+}
+function makeExpression(expressionKind, render, expressionCategory, result) {
+	return attachResultValue(Object.freeze({
+		expressionKind,
+		...expressionCategory ? { expressionCategory } : {},
+		...fragment(render)
+	}), result);
+}
+/** Mark a query-only expression category without changing its SQL renderer. */
+function markExpressionCategory(expression, category) {
+	return Object.freeze({
+		...expression,
+		expressionCategory: category
+	});
+}
+/**
+* Mark a built-in or explicitly audited renderer as schema-deterministic. Prefer
+* {@link defineSchemaExpression} for application extensions because it supplies a restricted schema
+* rendering context.
+*/
+function makeSchemaExpression(expressionKind, render, result) {
+	const expression = makeExpression(expressionKind, render, void 0, result);
+	return Object.freeze({
+		...expression,
+		[schemaExpressionBrand]: true
+	});
+}
+/** Add the schema-determinism brand to an explicitly audited expression. */
+function markSchemaExpression(expression) {
+	if (isSchemaExpression(expression)) return expression;
+	return Object.freeze({
+		...expression,
+		[schemaExpressionBrand]: true
+	});
+}
+/** Test the runtime brand used by schema rendering and validation. */
+function isSchemaExpression(value) {
+	return typeof value === "object" && value !== null && schemaExpressionBrand in value && value[schemaExpressionBrand] === true;
+}
+function isExpression(value) {
+	return typeof value === "object" && value !== null && "expressionKind" in value && "render" in value && typeof value.render === "function";
+}
+//#endregion
+//#region src/core/naming.ts
+/** Convert an application-facing field name to a SQL-facing identifier. */
+function snakeCaseIdentifier(name) {
+	return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+}
+function resolveSqlNames(fields) {
+	const sqlNames = {};
+	const fieldsBySqlName = /* @__PURE__ */ new Map();
+	for (const field of fields) {
+		const sqlName = field.sqlName ?? snakeCaseIdentifier(field.fieldName);
+		if (sqlName.length === 0) throw new Error(`SQL name for field "${field.fieldName}" cannot be empty`);
+		const existingField = fieldsBySqlName.get(sqlName);
+		if (existingField) throw new Error(`Fields "${existingField}" and "${field.fieldName}" both resolve to SQL name "${sqlName}"`);
+		fieldsBySqlName.set(sqlName, field.fieldName);
+		sqlNames[field.fieldName] = sqlName;
+	}
+	return Object.freeze(sqlNames);
+}
+//#endregion
+//#region src/schema/metadata.ts
+/** Error raised when relational metadata cannot be represented safely. */
+var SchemaMetadataValidationError = class extends TypeError {
+	name = "SchemaMetadataValidationError";
+	diagnostics;
+	issues;
+	constructor(diagnostics) {
+		const frozenDiagnostics = Object.freeze(diagnostics.map((diagnostic) => Object.freeze({
+			...diagnostic,
+			path: Object.freeze([...diagnostic.path]),
+			relatedPaths: diagnostic.relatedPaths ? Object.freeze(diagnostic.relatedPaths.map((path) => Object.freeze([...path]))) : void 0
+		})));
+		super(frozenDiagnostics.map((diagnostic) => diagnostic.message).join("\n"));
+		this.diagnostics = frozenDiagnostics;
+		this.issues = frozenDiagnostics;
+	}
+};
+/** Generate the version-one physical name for a relational object ID. */
+function generatedSchemaObjectName(id) {
+	return snakeCaseIdentifier(id);
+}
+/** Deep-freeze plain metadata values without introducing executable nodes. */
+function freezeSchemaMetadata(value) {
+	if (Array.isArray(value)) return Object.freeze(value.map((item) => freezeSchemaMetadata(item)));
+	if (typeof value !== "object" || value === null) return value;
+	const frozen = Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, freezeSchemaMetadata(nested)]));
+	return Object.freeze(frozen);
+}
+/** Check the portable identifier subset used for generated metadata names. */
+function isValidSchemaObjectName(name) {
+	return name.length > 0 && name === name.trim() && !/[.\\/\u0000-\u001f\u007f"']/u.test(name);
+}
+/**
+* Attach a record key and resolved physical name without changing the enumerable shape of legacy
+* constraint/index values. The properties are still ordinary read-only runtime metadata and are
+* available to snapshot traversals.
+*/
+function materializeSchemaObjectIdentity(value, id, physicalName) {
+	const materialized = { ...value };
+	Object.defineProperties(materialized, {
+		id: {
+			configurable: false,
+			enumerable: false,
+			value: id,
+			writable: false
+		},
+		physicalName: {
+			configurable: false,
+			enumerable: false,
+			value: physicalName ?? generatedSchemaObjectName(id),
+			writable: false
+		}
+	});
+	return Object.freeze(materialized);
+}
+/**
+* Resolve and validate names for one metadata record. The caller decides whether constraint and
+* index names share a database namespace.
+*/
+function materializeSchemaObjectRecord(record, kind) {
+	const diagnostics = [];
+	const names = /* @__PURE__ */ new Map();
+	const result = {};
+	for (const [id, value] of Object.entries(record)) {
+		const physicalName = value.physicalName ?? generatedSchemaObjectName(id);
+		const path = [kind === "constraint" ? "constraints" : "indexes", id];
+		if (!isValidSchemaObjectName(physicalName)) diagnostics.push({
+			code: "invalid-physical-name",
+			message: `The ${kind} "${id}" has invalid physical name "${physicalName}"`,
+			path: [...path, "physicalName"]
+		});
+		const previousId = names.get(physicalName);
+		if (previousId !== void 0) diagnostics.push({
+			code: "duplicate-physical-name",
+			message: `The ${kind}s "${previousId}" and "${id}" both use physical name "${physicalName}"`,
+			path: [...path, "physicalName"],
+			relatedPaths: [[
+				kind === "constraint" ? "constraints" : "indexes",
+				previousId,
+				"physicalName"
+			]]
+		});
+		else names.set(physicalName, id);
+		result[id] = materializeSchemaObjectIdentity(value, id, physicalName);
+	}
+	if (diagnostics.length > 0) throw new SchemaMetadataValidationError(diagnostics);
+	return Object.freeze(result);
+}
+/** Return a diagnostic when a dialect extension is used by another adapter. */
+function dialectMismatchDiagnostic(extension, dialect, path) {
+	if (extension.dialect === dialect) return;
+	return {
+		code: "dialect-mismatch",
+		message: `Dialect extension belongs to "${extension.dialect}" but the active schema dialect is "${dialect}"`,
+		path,
+		dialect
+	};
+}
+/** Throw a structured error for one or more dialect capability findings. */
+function assertSchemaDialectSupport(diagnostics) {
+	if (diagnostics.length > 0) throw new SchemaMetadataValidationError(diagnostics);
+}
+//#endregion
+//#region src/core/primitives/parameter.ts
+function parameter(_value) {
+	return fragment((context) => context.parameter(_value));
+}
+//#endregion
+//#region src/expressions/value.ts
+function value(input) {
+	const expression = makeSchemaExpression("value", (context) => context.render(parameter(input)));
+	return Object.freeze({
+		...expression,
+		value: input
+	});
+}
+/** Bind a value while declaring its SQL semantic domain. */
+function typedValue(input) {
+	return value(input);
+}
+function isExpressionValue(valueToCheck) {
+	return typeof valueToCheck === "object" && valueToCheck !== null && "expressionKind" in valueToCheck && "render" in valueToCheck && typeof valueToCheck.render === "function";
+}
+function isValueExpression(valueToCheck) {
+	return isExpressionValue(valueToCheck) && valueToCheck.expressionKind === "value" && "value" in valueToCheck;
+}
+function asValue(input) {
+	return isExpressionValue(input) ? input : value(input);
+}
+//#endregion
+//#region src/core/primitives/identifier.ts
+function identifier(name) {
+	return fragment((context) => context.append(context.dialect.quoteIdentifier(name)));
+}
+function qualifiedIdentifier(...parts) {
+	return fragment((context) => {
+		parts.forEach((part, index) => {
+			if (index > 0) context.append(".");
+			context.append(context.dialect.quoteIdentifier(part));
+		});
+	});
+}
+//#endregion
+//#region src/expressions/column.ts
+function createColumnReference(columnName, sourceReference, fieldName, result) {
+	const expression = makeSchemaExpression("column", (context) => {
+		if (context.renderColumnReference) {
+			context.renderColumnReference(columnName);
+			return;
+		}
+		context.render(sourceReference);
+		context.append(".");
+		context.render(identifier(columnName));
+	}, result);
+	return Object.freeze({
+		...expression,
+		fieldName,
+		columnName
+	});
+}
+function isColumnReference(value) {
+	return typeof value === "object" && value !== null && "expressionKind" in value && value.expressionKind === "column";
+}
+/** Turn an expression into a fragment that renders it without changing it. */
+function expressionFragment(expression) {
+	return fragment((context) => context.render(expression));
+}
+//#endregion
+export { parenthesize as A, resultValueOf as B, makeExpression as C, withDialectCapability as D, markSchemaExpression as E, dateResultDecoder as F, standardDialect as H, decodeResultRow as I, jsonTextResultDecoder as L, ResultDecodingError as M, booleanResultDecoder as N, fragment as O, createResultShape as P, resultShapeValue as R, isSchemaExpression as S, markExpressionCategory as T, timestampResultDecoder as V, materializeSchemaObjectIdentity as _, qualifiedIdentifier as a, snakeCaseIdentifier as b, typedValue as c, SchemaMetadataValidationError as d, assertSchemaDialectSupport as f, isValidSchemaObjectName as g, generatedSchemaObjectName as h, identifier as i, sequence as j, isFragment as k, value as l, freezeSchemaMetadata as m, expressionFragment as n, asValue as o, dialectMismatchDiagnostic as p, isColumnReference as r, isValueExpression as s, createColumnReference as t, parameter as u, materializeSchemaObjectRecord as v, makeSchemaExpression as w, isExpression as x, resolveSqlNames as y, resultValue as z };