qubu 0.0.0 → 0.3.3

package/dist/codegen.d.mts

@@ -0,0 +1,107 @@
+import { St as IntrospectionDiagnostic, dt as IntrospectionResult, i as CatalogClassificationConfidence, p as CatalogDialect, z as CatalogPortableStorageType } from "./types-BX0mckiU.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';
+/** Qubu SQL semantic domains that generated columns can carry. */
+type CodegenSqlDomain = 'unknown' | 'integer' | 'decimal' | 'text' | 'boolean' | 'date' | 'timestamp' | 'uuid' | 'json' | 'bigint' | 'binary';
+/** One logical-name decision exposed to a generator naming callback. */
+interface CodegenNameContext {
+  readonly kind: 'schema' | 'table' | 'column' | 'constraint' | 'index';
+  readonly physicalName: string;
+  readonly suggestedName: string;
+  readonly tablePhysicalName?: string;
+  readonly tableName?: string;
+}
+/** Catalog facts available to a controlled column mapping callback. */
+interface CodegenColumnContext {
+  readonly dialect: CatalogDialect;
+  readonly namespace: string;
+  readonly tablePhysicalName: string;
+  readonly tableName: string;
+  readonly columnPhysicalName: string;
+  readonly columnName: string;
+  readonly nativeType: string;
+  readonly portableType?: CatalogPortableStorageType;
+  readonly classificationConfidence?: CatalogClassificationConfidence;
+  readonly suggestedSqlDomain: CodegenSqlDomain;
+}
+/** Trusted type choices for one generated column. */
+interface CodegenColumnMapping {
+  /** Selected application value type. Defaults to `unknown`. */
+  readonly output?: CodegenApplicationType;
+  /** Insert value type. Defaults to `unknown`. */
+  readonly insert?: CodegenApplicationType;
+  /** Update value type. Defaults to `unknown`. */
+  readonly update?: CodegenApplicationType;
+  /** SQL semantic domain. Defaults to the conservative catalog mapping. */
+  readonly sqlDomain?: CodegenSqlDomain;
+}
+/** Controlled customization points for generated logical names and types. */
+interface SchemaCodegenOptions {
+  /**
+   * Override one suggested camelCase name. The returned value must still be a
+   * safe camelCase logical ID, and table and schema names must be valid export
+   * bindings.
+   */
+  readonly naming?: (context: CodegenNameContext) => string | undefined;
+  /**
+   * Override trusted application types or a Qubu SQL domain for one column.
+   * The callback selects from fixed tokens and cannot inject source text.
+   */
+  readonly mapColumn?: (context: CodegenColumnContext) => CodegenColumnMapping | undefined;
+}
+/** Stable generator findings added beside retained introspection diagnostics. */
+type CodegenDiagnosticCode = IntrospectionDiagnostic['code'] | 'invalid-input' | 'lossy-input' | 'unsupported-snapshot' | 'omitted-fact' | 'unsafe-name' | 'name-collision' | 'invalid-option' | 'unrepresentable-fact' | 'excluded-object-family' | 'unsafe-source';
+/** A path-addressed finding returned by schema source generation. */
+interface CodegenDiagnostic extends Omit<IntrospectionDiagnostic, 'code'> {
+  readonly code: CodegenDiagnosticCode;
+  readonly relatedPaths?: readonly (readonly (string | number)[])[];
+}
+/** Successful source generation with all retained warnings and information. */
+interface SchemaCodegenSuccess {
+  readonly ok: true;
+  readonly source: string;
+  readonly diagnostics: readonly CodegenDiagnostic[];
+}
+/** Failed generation. No partial source is returned. */
+interface SchemaCodegenFailure {
+  readonly ok: false;
+  readonly source?: never;
+  readonly diagnostics: readonly CodegenDiagnostic[];
+}
+/** Non-throwing result returned by schema source generation. */
+type SchemaCodegenResult = SchemaCodegenSuccess | SchemaCodegenFailure;
+//#endregion
+//#region src/codegen/generate.d.ts
+/**
+ * Generate a deterministic TypeScript module from one introspection result.
+ *
+ * @remarks
+ * Generation accepts only a successful, non-lossy Snapshot v1 result for one
+ * PostgreSQL, SQLite, or MySQL namespace. It is pure: it opens no connection,
+ * performs no filesystem writes, and never evaluates catalog SQL. Existing
+ * introspection diagnostics are copied into the result. Any error returns no
+ * source.
+ *
+ * The generated module exports every ordinary table plus one schema registry.
+ * Physical names and native declarations remain escaped string literals.
+ * Catalog expressions use dialect-tagged schema data, checks use
+ * `catalogCheck()`, and foreign keys use lazy `catalogForeignKey()` targets.
+ * Foreign keys must have equal local and target arity and target an exact
+ * primary key, strict unique key, or candidate index. Nullable database UNIQUE
+ * constraints do not provide that candidate-key proof and fail generation.
+ *
+ * Application output, insert, and update types default independently to
+ * `unknown`. The generator may attach a conservative SQL semantic domain, and
+ * {@link SchemaCodegenOptions.mapColumn} can override either type axis with a
+ * fixed token. Naming callbacks can replace suggested camelCase IDs, but they
+ * cannot supply source syntax.
+ *
+ * @param input A completed introspection operation. Failed and lossy results
+ * are reported as diagnostics rather than thrown errors.
+ * @param options Controlled logical-name and column-type mappings.
+ * @returns Generated source and diagnostics, or diagnostics without source.
+ */
+declare function generateSchemaSource(input: IntrospectionResult, options?: SchemaCodegenOptions): SchemaCodegenResult;
+//#endregion
+export { type CodegenApplicationType, type CodegenColumnContext, type CodegenColumnMapping, type CodegenDiagnostic, type CodegenDiagnosticCode, type CodegenNameContext, type CodegenSqlDomain, type SchemaCodegenFailure, type SchemaCodegenOptions, type SchemaCodegenResult, type SchemaCodegenSuccess, generateSchemaSource };