shapecraft 1.0.0

package/packages/core/src/shape/transforms/json-schema/types.ts

@@ -0,0 +1,132 @@
+import type { NumberTag } from "../../tags";
+
+export type JSONSchemaTypeName =
+  | "string" //
+  | "number"
+  | "integer"
+  | "boolean"
+  | "object"
+  | "array"
+  | "null";
+
+export interface ShapecraftMeta {
+  kind?:
+    | "date"
+    | "binary"
+    | "undefined"
+    | "vector"
+    | "range"
+    | "tuple"
+    | undefined;
+  numberTag?: NumberTag | undefined;
+  vectorDims?: number | undefined;
+  tupleLen?: number | undefined;
+  unique?: boolean | undefined;
+  primary?: boolean | undefined;
+  foreign?: { table: string; column: string } | undefined;
+  optional?: boolean | undefined;
+  anchor?: string | undefined;
+}
+
+export type JSONSchemaType =
+  | string //
+  | number
+  | boolean
+  | JSONSchemaObject
+  | JSONSchemaArray
+  | null;
+
+export interface JSONSchemaObject {
+  [key: string]: JSONSchemaType;
+}
+
+export interface JSONSchemaArray extends Array<JSONSchemaType> {}
+
+export type JSONSchemaVersion = string;
+
+export type JSONSchemaDefinition = JSONSchema | boolean;
+export interface JSONSchema {
+  $id?: string | undefined;
+  $ref?: string | undefined;
+  $schema?: JSONSchemaVersion | undefined;
+  $comment?: string | undefined;
+  $anchor?: string | undefined;
+
+  $defs?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+
+  type?: JSONSchemaTypeName | JSONSchemaTypeName[] | undefined;
+  enum?: JSONSchemaType[] | undefined;
+  const?: JSONSchemaType | undefined;
+
+  multipleOf?: number | undefined;
+  maximum?: number | undefined;
+  exclusiveMaximum?: number | undefined;
+  minimum?: number | undefined;
+  exclusiveMinimum?: number | undefined;
+
+  maxLength?: number | undefined;
+  minLength?: number | undefined;
+  pattern?: string | undefined;
+
+  items?: JSONSchemaDefinition | JSONSchemaDefinition[] | undefined;
+  prefixItems?: JSONSchemaDefinition[] | undefined;
+  additionalItems?: JSONSchemaDefinition | undefined;
+  maxItems?: number | undefined;
+  minItems?: number | undefined;
+  uniqueItems?: boolean | undefined;
+  contains?: JSONSchemaDefinition | undefined;
+
+  maxProperties?: number | undefined;
+  minProperties?: number | undefined;
+  required?: string[] | undefined;
+  properties?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+  patternProperties?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+  additionalProperties?: JSONSchemaDefinition | undefined;
+  dependencies?:
+    | {
+        [key: string]: JSONSchemaDefinition | string[];
+      }
+    | undefined;
+  propertyNames?: JSONSchemaDefinition | undefined;
+
+  if?: JSONSchemaDefinition | undefined;
+  then?: JSONSchemaDefinition | undefined;
+  else?: JSONSchemaDefinition | undefined;
+
+  allOf?: JSONSchemaDefinition[] | undefined;
+  anyOf?: JSONSchemaDefinition[] | undefined;
+  oneOf?: JSONSchemaDefinition[] | undefined;
+  not?: JSONSchemaDefinition | undefined;
+
+  format?: string | undefined;
+
+  contentMediaType?: string | undefined;
+  contentEncoding?: string | undefined;
+
+  definitions?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+
+  title?: string | undefined;
+  description?: string | undefined;
+  default?: JSONSchemaType | undefined;
+  readOnly?: boolean | undefined;
+  writeOnly?: boolean | undefined;
+  examples?: JSONSchemaType | undefined;
+
+  "x-shapecraft"?: ShapecraftMeta | undefined;
+}

package/packages/core/src/shape/transforms/sql/dialects/dialect.ts

@@ -0,0 +1,89 @@
+import { R } from "../../../../common/result";
+import { shapes } from "../../../shape";
+import { SQLDialect } from "../options";
+
+export type Prelude = { name: string; sql: string };
+
+export type ColumnDef = {
+  name: string;
+  type: string;
+  notNull: boolean;
+  primary: boolean;
+  unique: boolean;
+  identity: boolean;
+  defaultExpr?: string;
+  references?: string;
+  generated?: { expression: string; stored: boolean };
+  checks: string[];
+  comments: string[];
+};
+
+export type TypeRendering = {
+  type: string;
+  checks: string[];
+  prelude: Prelude[];
+};
+
+export type FormatDefault =
+  | { ok: true; expr: string }
+  | { ok: false; reason: string };
+
+export interface Dialect {
+  readonly name: SQLDialect;
+
+  // True iff `anno.schema` is meaningful in this dialect. SQLite has no schemas.
+  readonly supportsSchema: boolean;
+
+  // Trailing tokens emitted after the closing paren of a CREATE TABLE
+  // (e.g. " STRICT" for SQLite). Empty string for postgres.
+  readonly tableTrailer: string;
+
+  // Convert a column's shape into a dialect-specific type string + per-type
+  // CHECK fragments + any prelude statements (named ENUM types, helper
+  // functions, etc.). Handles per-shape concerns only — primary/unique/default
+  // /foreign/autoIncrement are applied uniformly by convertField afterwards.
+  renderType(
+    name: string,
+    shape: shapes.Shape,
+  ): R.Result<TypeRendering, string[]>;
+
+  // Validate and apply autoIncrement annotation to a ColumnDef. Some dialects
+  // (SQLite) require autoIncrement columns to also be PRIMARY KEY and have a
+  // specific integer affinity; this hook lets the dialect enforce that.
+  applyAutoIncrement(
+    name: string,
+    shape: shapes.Shape,
+    col: ColumnDef,
+  ): string[];
+
+  // Format a literal default value into an SQL expression appropriate for the
+  // dialect. Casts (`::timestamptz`, `::jsonb`) are postgres-only.
+  formatDefault(v: unknown, columnType: string): FormatDefault;
+
+  // Validate the top-level mapping's annotations against dialect constraints.
+  // Returns an array of error messages — SQLite errors here on anno.schema.
+  validateMappingAnno(anno: shapes.Shape["anno"], title: string): string[];
+
+  // Render schema-creation prelude (e.g. CREATE SCHEMA IF NOT EXISTS "x";).
+  // SQLite returns the empty string and validateMappingAnno will have caught
+  // the misuse upstream.
+  schemaPrelude(name: string): string;
+
+  // Render a qualified or bare table name.
+  qualifiedTable(schema: string | undefined, title: string): string;
+
+  // Render a column definition line (no leading indent, no trailing comma).
+  // Dialects may special-case (e.g. SQLite collapses INTEGER+identity+primary
+  // into `INTEGER PRIMARY KEY AUTOINCREMENT`).
+  renderColumn(c: ColumnDef): string;
+
+  // Final validation pass after all columns are converted but before SQL is
+  // rendered. SQLite uses this to enforce single-PK constraints around
+  // AUTOINCREMENT columns.
+  finalizeColumns(cols: ColumnDef[]): string[];
+}
+
+export const quoteIdent = (name: string): string =>
+  `"${name.replace(/"/g, '""')}"`;
+
+export const quoteLit = (s: string): string => `'${s.replace(/'/g, "''")}'`;

package/packages/core/src/shape/transforms/sql/dialects/index.ts

@@ -0,0 +1,14 @@
+import { SQLDialect } from "../options";
+import { Dialect } from "./dialect";
+import { postgresDialect } from "./postgres";
+import { sqliteDialect } from "./sqlite";
+
+export type { Dialect, ColumnDef, Prelude } from "./dialect";
+export { quoteIdent, quoteLit } from "./dialect";
+export { renderReferentialActions } from "./postgres";
+
+export const getDialect = (name: SQLDialect): Dialect => {
+  if (name === "postgres") return postgresDialect;
+  if (name === "sqlite") return sqliteDialect;
+  throw new Error(`unknown dialect: ${name}`);
+};

package/packages/core/src/shape/transforms/sql/dialects/postgres.ts

@@ -0,0 +1,392 @@
+import { R } from "../../../../common/result";
+import { ReferentialAction } from "../../../annotation";
+import { shapes } from "../../../shape";
+import { NumberTag } from "../../../tags";
+import {
+  ColumnDef,
+  Dialect,
+  FormatDefault,
+  Prelude,
+  quoteIdent,
+  quoteLit,
+  TypeRendering,
+} from "./dialect";
+
+const INT_RANGES: Record<string, { minimum?: number; maximum?: number }> = {
+  int8: { minimum: -128, maximum: 127 },
+  uint8: { minimum: 0, maximum: 255 },
+  int16: { minimum: -32768, maximum: 32767 },
+  uint16: { minimum: 0, maximum: 65535 },
+  int32: { minimum: -2_147_483_648, maximum: 2_147_483_647 },
+  uint32: { minimum: 0, maximum: 4_294_967_295 },
+  uint64: { minimum: 0 },
+};
+
+const INT_PG_TYPE: Record<string, string> = {
+  int: "bigint",
+  int8: "smallint",
+  uint8: "smallint",
+  int16: "smallint",
+  uint16: "integer",
+  int32: "integer",
+  uint32: "bigint",
+  int64: "bigint",
+  uint64: "numeric(20,0)",
+};
+
+const FLOAT_PG_TYPE: Record<string, string> = {
+  number: "double precision",
+  float: "real",
+  float32: "real",
+  float64: "double precision",
+};
+
+const isIntTag = (tag: NumberTag): boolean => tag in INT_PG_TYPE;
+
+const ARRAY_IS_UNIQUE_FN = "shapecraft_array_is_unique";
+const ARRAY_IS_UNIQUE_FN_SQL =
+  `CREATE OR REPLACE FUNCTION ${ARRAY_IS_UNIQUE_FN}(anyarray) RETURNS boolean\n` +
+  `  LANGUAGE sql IMMUTABLE PARALLEL SAFE\n` +
+  `  AS $$ SELECT cardinality($1) = cardinality(ARRAY(SELECT DISTINCT unnest($1))) $$;`;
+
+const pgTypeRange = (
+  pgType: string,
+): { minimum?: number; maximum?: number } => {
+  if (pgType === "smallint") return { minimum: -32768, maximum: 32767 };
+  if (pgType === "integer")
+    return { minimum: -2_147_483_648, maximum: 2_147_483_647 };
+  return {};
+};
+
+const formatNumberLit = (n: number): string => {
+  if (!isFinite(n)) return `${quoteLit(String(n))}::double precision`;
+  return String(n);
+};
+
+const REFERENTIAL_ACTION_SQL: Record<ReferentialAction, string> = {
+  cascade: "CASCADE",
+  restrict: "RESTRICT",
+  setNull: "SET NULL",
+  setDefault: "SET DEFAULT",
+  noAction: "NO ACTION",
+};
+
+export const renderReferentialActions = (foreign: {
+  onDelete?: ReferentialAction;
+  onUpdate?: ReferentialAction;
+}): string => {
+  const parts: string[] = [];
+  if (foreign.onDelete !== undefined) {
+    parts.push(`ON DELETE ${REFERENTIAL_ACTION_SQL[foreign.onDelete]}`);
+  }
+  if (foreign.onUpdate !== undefined) {
+    parts.push(`ON UPDATE ${REFERENTIAL_ACTION_SQL[foreign.onUpdate]}`);
+  }
+  return parts.length > 0 ? " " + parts.join(" ") : "";
+};
+
+const rangePgType = (shape: shapes.ShapeRange): string => {
+  const item = shape.input;
+  if (item.type === "date") {
+    if (shape.anno.format === "pgtype:tsrange") return "tsrange";
+    if (shape.anno.format === "pgtype:daterange") return "daterange";
+    return "tstzrange";
+  }
+  if (item.type === "number") {
+    if (item.tag === "int32" || item.tag === "int16") return "int4range";
+    if (item.tag === "int64" || item.tag === "int") return "int8range";
+    return "numrange";
+  }
+  return "tstzrange";
+};
+
+const arrayElementPgType = (s: shapes.Shape): string | null => {
+  if (s.type === "string") {
+    if (s.literal) return null;
+    if (s.anno.max !== undefined) return `varchar(${s.anno.max})`;
+    return "text";
+  }
+  if (s.type === "boolean") {
+    if (s.literal) return null;
+    return "boolean";
+  }
+  if (s.type === "number") {
+    if (s.literal) return null;
+    if (isIntTag(s.tag)) return INT_PG_TYPE[s.tag] ?? "bigint";
+    return FLOAT_PG_TYPE[s.tag] ?? "double precision";
+  }
+  if (s.type === "date") return "timestamptz";
+  if (s.type === "binary") return "bytea";
+  return null;
+};
+
+const unionEnumValues = (u: shapes.ShapeUnion): string[] | null => {
+  const variants = Array.from(u.input) as shapes.Shape[];
+  if (variants.length === 0) return null;
+  const values: string[] = [];
+  for (const v of variants) {
+    if (v.type !== "string" || v.literal !== true) return null;
+    values.push(v.input as string);
+  }
+  return values;
+};
+
+const renderType = (
+  name: string,
+  shape: shapes.Shape,
+): R.Result<TypeRendering, string[]> => {
+  const errors: string[] = [];
+  const prelude: Prelude[] = [];
+  const checks: string[] = [];
+  let pgType: string | null = null;
+
+  if (shape.type === "union") {
+    const values = unionEnumValues(shape);
+    if (values !== null) {
+      const enumName = shape.anno.title;
+      if (enumName !== undefined) {
+        const sql = `CREATE TYPE ${quoteIdent(enumName)} AS ENUM (${values
+          .map(quoteLit)
+          .join(", ")});`;
+        prelude.push({ name: enumName, sql });
+        pgType = quoteIdent(enumName);
+      } else {
+        pgType = "text";
+        checks.push(
+          `${quoteIdent(name)} IN (${values.map(quoteLit).join(", ")})`,
+        );
+      }
+    } else {
+      pgType = "jsonb";
+    }
+  } else {
+    switch (shape.type) {
+      case "string": {
+        if (shape.literal) {
+          pgType = "text";
+          checks.push(
+            `${quoteIdent(name)} = ${quoteLit(shape.input as string)}`,
+          );
+        } else {
+          if (shape.anno.max !== undefined) {
+            pgType = `varchar(${shape.anno.max})`;
+          } else {
+            pgType = "text";
+          }
+          if (shape.anno.min !== undefined) {
+            checks.push(
+              `char_length(${quoteIdent(name)}) >= ${shape.anno.min}`,
+            );
+          }
+          if (shape.anno.pattern !== undefined) {
+            const src =
+              shape.anno.pattern instanceof RegExp ?
+                shape.anno.pattern.source
+              : shape.anno.pattern;
+            checks.push(`${quoteIdent(name)} ~ ${quoteLit(src)}`);
+          }
+        }
+        break;
+      }
+      case "boolean": {
+        pgType = "boolean";
+        if (shape.literal) {
+          const v = shape.input as boolean;
+          checks.push(`${quoteIdent(name)} IS ${v ? "TRUE" : "FALSE"}`);
+        }
+        break;
+      }
+      case "number": {
+        if (shape.literal) {
+          if (isIntTag(shape.tag)) {
+            pgType = INT_PG_TYPE[shape.tag] ?? "bigint";
+          } else {
+            pgType = FLOAT_PG_TYPE[shape.tag] ?? "double precision";
+          }
+          checks.push(
+            `${quoteIdent(name)} = ${formatNumberLit(shape.input as number)}`,
+          );
+        } else if (isIntTag(shape.tag)) {
+          pgType = INT_PG_TYPE[shape.tag] ?? "bigint";
+          const natural = INT_RANGES[shape.tag];
+          let effMin: number | undefined = natural?.minimum;
+          let effMax: number | undefined = natural?.maximum;
+          if (shape.anno.min !== undefined) {
+            effMin =
+              effMin === undefined ?
+                shape.anno.min
+              : Math.max(effMin, shape.anno.min);
+          }
+          if (shape.anno.max !== undefined) {
+            effMax =
+              effMax === undefined ?
+                shape.anno.max
+              : Math.min(effMax, shape.anno.max);
+          }
+          const pgr = pgTypeRange(pgType);
+          if (
+            effMin !== undefined &&
+            (pgr.minimum === undefined || effMin > pgr.minimum)
+          ) {
+            checks.push(`${quoteIdent(name)} >= ${effMin}`);
+          }
+          if (
+            effMax !== undefined &&
+            (pgr.maximum === undefined || effMax < pgr.maximum)
+          ) {
+            checks.push(`${quoteIdent(name)} <= ${effMax}`);
+          }
+        } else {
+          pgType = FLOAT_PG_TYPE[shape.tag] ?? "double precision";
+          if (shape.anno.min !== undefined)
+            checks.push(`${quoteIdent(name)} >= ${shape.anno.min}`);
+          if (shape.anno.max !== undefined)
+            checks.push(`${quoteIdent(name)} <= ${shape.anno.max}`);
+        }
+        break;
+      }
+      case "date":
+        pgType = "timestamptz";
+        break;
+      case "binary":
+        pgType = "bytea";
+        break;
+      case "unknown":
+        pgType = "jsonb";
+        break;
+      case "nil":
+        errors.push(`field '${name}': nil cannot be a column`);
+        break;
+      case "undefined":
+        errors.push(`field '${name}': undefined cannot be a column`);
+        break;
+      case "array": {
+        const elt = arrayElementPgType(shape.input);
+        pgType = elt !== null ? `${elt}[]` : "jsonb";
+        if (shape.anno.min !== undefined)
+          checks.push(`cardinality(${quoteIdent(name)}) >= ${shape.anno.min}`);
+        if (shape.anno.max !== undefined)
+          checks.push(`cardinality(${quoteIdent(name)}) <= ${shape.anno.max}`);
+        if (shape.anno.uniqueItems === true) {
+          if (pgType === "jsonb") {
+            errors.push(
+              `field '${name}': uniqueItems is not supported on jsonb array columns`,
+            );
+          } else {
+            prelude.push({
+              name: ARRAY_IS_UNIQUE_FN,
+              sql: ARRAY_IS_UNIQUE_FN_SQL,
+            });
+            checks.push(`${ARRAY_IS_UNIQUE_FN}(${quoteIdent(name)})`);
+          }
+        }
+        break;
+      }
+      case "vector":
+        pgType = `vector(${shape.input.dims})`;
+        break;
+      case "range": {
+        pgType = rangePgType(shape);
+        break;
+      }
+      case "mapping":
+      case "record":
+        pgType = "jsonb";
+        break;
+      case "tuple": {
+        pgType = "jsonb";
+        const len = shape.input.length;
+        checks.push(
+          `jsonb_typeof(${quoteIdent(name)}) = 'array' AND jsonb_array_length(${quoteIdent(name)}) = ${len}`,
+        );
+        break;
+      }
+    }
+  }
+
+  if (pgType === null) {
+    return R.err(errors);
+  }
+  if (errors.length > 0) return R.err(errors);
+
+  return R.ok({ type: pgType, checks, prelude });
+};
+
+const formatDefault = (v: unknown, columnType: string): FormatDefault => {
+  if (v === null) return { ok: true, expr: "NULL" };
+  if (typeof v === "string") return { ok: true, expr: quoteLit(v) };
+  if (typeof v === "number") return { ok: true, expr: formatNumberLit(v) };
+  if (typeof v === "boolean") return { ok: true, expr: v ? "TRUE" : "FALSE" };
+  if (v instanceof Date)
+    return {
+      ok: true,
+      expr: `${quoteLit(v.toISOString())}::timestamptz`,
+    };
+  if (typeof v === "object" && columnType === "jsonb") {
+    try {
+      return { ok: true, expr: `${quoteLit(JSON.stringify(v))}::jsonb` };
+    } catch {
+      return { ok: false, reason: "default value could not be JSON-encoded" };
+    }
+  }
+  return {
+    ok: false,
+    reason: `default value of type ${typeof v} is not supported for column type ${columnType}`,
+  };
+};
+
+const applyAutoIncrement = (
+  name: string,
+  shape: shapes.Shape,
+  col: ColumnDef,
+): string[] => {
+  if (shape.type !== "number" || !isIntTag(shape.tag)) {
+    return [`field '${name}': autoIncrement requires an integer type`];
+  }
+  if (shape.tag === "uint64") {
+    return [
+      `field '${name}': autoIncrement is not supported on uint64 (numeric column)`,
+    ];
+  }
+  col.identity = true;
+  return [];
+};
+
+const renderColumn = (c: ColumnDef): string => {
+  const parts: string[] = [quoteIdent(c.name), c.type];
+  if (c.generated !== undefined) {
+    parts.push(
+      `GENERATED ALWAYS AS (${c.generated.expression}) ${c.generated.stored ? "STORED" : "VIRTUAL"}`,
+    );
+    if (c.primary) parts.push("PRIMARY KEY");
+    if (c.unique) parts.push("UNIQUE");
+    if (c.references !== undefined) parts.push(`REFERENCES ${c.references}`);
+    for (const chk of c.checks) parts.push(`CHECK (${chk})`);
+    return parts.join(" ");
+  }
+  if (c.notNull) parts.push("NOT NULL");
+  if (c.primary) parts.push("PRIMARY KEY");
+  if (c.unique) parts.push("UNIQUE");
+  if (c.identity) parts.push("GENERATED ALWAYS AS IDENTITY");
+  if (c.defaultExpr !== undefined) parts.push(`DEFAULT ${c.defaultExpr}`);
+  if (c.references !== undefined) parts.push(`REFERENCES ${c.references}`);
+  for (const chk of c.checks) parts.push(`CHECK (${chk})`);
+  return parts.join(" ");
+};
+
+export const postgresDialect: Dialect = {
+  name: "postgres",
+  supportsSchema: true,
+  tableTrailer: "",
+  renderType,
+  applyAutoIncrement,
+  formatDefault,
+  validateMappingAnno: (_anno, _title) => [],
+  schemaPrelude: (name) => `CREATE SCHEMA IF NOT EXISTS ${quoteIdent(name)};`,
+  qualifiedTable: (schema, title) =>
+    schema !== undefined ?
+      `${quoteIdent(schema)}.${quoteIdent(title)}`
+    : quoteIdent(title),
+  renderColumn,
+  finalizeColumns: () => [],
+};