@shapecraft/core 1.0.0

package/src/shape/transforms/sql/transform.ts

@@ -0,0 +1,295 @@
+import { R } from "../../../common/result";
+import { shapes } from "../../shape";
+import {
+  ColumnDef,
+  Dialect,
+  getDialect,
+  Prelude,
+  quoteIdent,
+  renderReferentialActions,
+} from "./dialects";
+import { resolveDialect, SQLOptions } from "./options";
+
+const collectComments = (shape: shapes.Shape): string[] => {
+  const comments: string[] = [];
+  if (shape.anno.description) comments.push(shape.anno.description);
+  if (shape.anno.comment) comments.push(shape.anno.comment);
+  if (shape.anno.format) comments.push(`(format: ${shape.anno.format})`);
+  if (shape.type === "union" && !shape.anno.format) {
+    const formats = shape.input
+      .map((m) => m.anno.format)
+      .filter((f): f is string => typeof f === "string");
+    if (formats.length > 0 && formats.length === shape.input.length) {
+      comments.push(`(format: ${formats.join(" | ")})`);
+    }
+  }
+  return comments;
+};
+
+const renderComments = (comments: string[], pad: string): string[] => {
+  if (comments.length === 0) return [];
+  if (comments.length === 1) return [`${pad}-- ${comments[0]}`];
+  return [`${pad}/*`, ...comments.map((c) => `${pad} * ${c}`), `${pad} */`];
+};
+
+type FieldOk = { column: ColumnDef; prelude: Prelude[] };
+type FieldResult = R.Result<FieldOk, string[]>;
+
+const convertField = (
+  name: string,
+  shape: shapes.Shape,
+  dialect: Dialect,
+): FieldResult => {
+  const errors: string[] = [];
+  const rendered = dialect.renderType(name, shape);
+  if (!R.isOk(rendered)) return R.err(rendered.error);
+  const { type, checks, prelude } = rendered.value;
+
+  const column: ColumnDef = {
+    name,
+    type,
+    notNull: shape.anno.optional !== true,
+    primary: shape.anno.primary === true,
+    unique: shape.anno.unique === true,
+    identity: false,
+    checks: [...checks],
+    comments: collectComments(shape),
+  };
+
+  if (column.primary) column.notNull = true;
+
+  if (shape.anno.autoIncrement === true) {
+    const aiErrors = dialect.applyAutoIncrement(name, shape, column);
+    errors.push(...aiErrors);
+  }
+
+  if (shape.anno.default !== undefined) {
+    const enc = dialect.formatDefault(shape.anno.default, type);
+    if (enc.ok) {
+      column.defaultExpr = enc.expr;
+    } else {
+      errors.push(`field '${name}': ${enc.reason}`);
+    }
+  } else if (shape.anno.defaultExpr !== undefined) {
+    column.defaultExpr = shape.anno.defaultExpr;
+  }
+
+  if (shape.anno.foreign !== undefined) {
+    column.references =
+      `${quoteIdent(shape.anno.foreign.table)}(${quoteIdent(
+        shape.anno.foreign.column,
+      )})` + renderReferentialActions(shape.anno.foreign);
+  }
+
+  if (shape.anno.check !== undefined) {
+    column.checks.push(shape.anno.check);
+  }
+
+  if (shape.anno.generated !== undefined) {
+    column.generated = shape.anno.generated;
+  }
+
+  if (errors.length > 0) return R.err(errors);
+
+  return R.ok({ column, prelude });
+};
+
+type TableResult = {
+  tableName: string;
+  schema?: string;
+  sql: string;
+  prelude: Prelude[];
+  deps: Set<string>;
+};
+
+const toSQLTable = (
+  shape: shapes.ShapeMapping,
+  dialect: Dialect,
+): R.Result<TableResult, string[]> => {
+  const title = shape.anno.title;
+  if (title === undefined) {
+    return R.err(["mapping is missing required title (table name)"]);
+  }
+
+  const annoErrors = dialect.validateMappingAnno(shape.anno, title);
+  if (annoErrors.length > 0) return R.err(annoErrors);
+
+  const errors: string[] = [];
+  const columns: ColumnDef[] = [];
+  const prelude: Prelude[] = [];
+  const deps = new Set<string>();
+
+  for (const [k, child] of Object.entries(shape.input)) {
+    const res = convertField(k, child, dialect);
+    if (R.isOk(res)) {
+      columns.push(res.value.column);
+      for (const p of res.value.prelude) prelude.push(p);
+      if (child.anno.foreign !== undefined) deps.add(child.anno.foreign.table);
+    } else {
+      errors.push(...res.error);
+    }
+  }
+
+  if (errors.length > 0) return R.err(errors);
+
+  const finalizeErrors = dialect.finalizeColumns(columns);
+  if (finalizeErrors.length > 0) return R.err(finalizeErrors);
+
+  const primaryCols = columns.filter((c) => c.primary);
+  let tableLevelPk: string | null = null;
+  if (primaryCols.length > 1) {
+    tableLevelPk = `PRIMARY KEY (${primaryCols
+      .map((c) => quoteIdent(c.name))
+      .join(", ")})`;
+    for (const c of primaryCols) c.primary = false;
+  }
+
+  const tableLevelUniques: string[] = [];
+  const ucs = shape.anno.uniqueConstraints;
+  if (ucs !== undefined) {
+    for (const uc of ucs) {
+      const cols = uc.columns.map(quoteIdent).join(", ");
+      const head =
+        uc.name !== undefined ?
+          `CONSTRAINT ${quoteIdent(uc.name)} UNIQUE (${cols})`
+        : `UNIQUE (${cols})`;
+      tableLevelUniques.push(head);
+    }
+  }
+
+  const renderedColumns: string[] = columns.map((c) => {
+    const commentLines = renderComments(c.comments, "  ");
+    const line = `  ${dialect.renderColumn(c)}`;
+    return commentLines.length > 0 ? [...commentLines, line].join("\n") : line;
+  });
+  if (tableLevelPk !== null) renderedColumns.push(`  ${tableLevelPk}`);
+  for (const u of tableLevelUniques) renderedColumns.push(`  ${u}`);
+  if (shape.anno.check !== undefined) {
+    renderedColumns.push(`  CHECK (${shape.anno.check})`);
+  }
+
+  const schema = shape.anno.schema;
+  const tableCommentLines = renderComments(collectComments(shape), "");
+  const header = [
+    ...tableCommentLines,
+    `CREATE TABLE IF NOT EXISTS ${dialect.qualifiedTable(schema, title)} (`,
+  ].join("\n");
+
+  const trailer = dialect.tableTrailer;
+  const sql = `${header}\n${renderedColumns.join(",\n")}\n)${trailer};`;
+
+  const result: TableResult = { tableName: title, sql, prelude, deps };
+  if (schema !== undefined && dialect.supportsSchema) result.schema = schema;
+  return R.ok(result);
+};
+
+const topoSortTables = (
+  tables: TableResult[],
+): R.Result<TableResult[], string[]> => {
+  const byName = new Map<string, TableResult>();
+  for (const t of tables) byName.set(t.tableName, t);
+
+  const indegree = new Map<string, number>();
+  for (const t of tables) {
+    let d = 0;
+    for (const dep of t.deps) {
+      if (dep !== t.tableName && byName.has(dep)) d += 1;
+    }
+    indegree.set(t.tableName, d);
+  }
+
+  const result: TableResult[] = [];
+  const ready = Array.from(indegree.entries())
+    .filter(([, d]) => d === 0)
+    .map(([n]) => n)
+    .sort();
+  while (ready.length > 0) {
+    const next = ready.shift()!;
+    const t = byName.get(next)!;
+    result.push(t);
+    for (const other of tables) {
+      if (other.tableName === next) continue;
+      if (other.deps.has(next)) {
+        const d = (indegree.get(other.tableName) ?? 0) - 1;
+        indegree.set(other.tableName, d);
+        if (d === 0 && !result.some((r) => r.tableName === other.tableName))
+          insertSorted(ready, other.tableName);
+      }
+    }
+  }
+
+  if (result.length < tables.length) {
+    const cycle = tables
+      .filter((t) => !result.some((r) => r.tableName === t.tableName))
+      .map((t) => t.tableName)
+      .sort();
+    return R.err([`FK cycle among tables: ${cycle.join(", ")}`]);
+  }
+
+  return R.ok(result);
+};
+
+const insertSorted = (arr: string[], v: string): void => {
+  let i = 0;
+  while (i < arr.length && (arr[i] ?? "") < v) i += 1;
+  arr.splice(i, 0, v);
+};
+
+export const toSQL = (
+  shape: shapes.Shape,
+  opts?: SQLOptions,
+): R.Result<string, string[]> => {
+  const dialect = getDialect(resolveDialect(opts));
+
+  if (shape.type === "mapping") {
+    const res = toSQLTable(shape, dialect);
+    if (!R.isOk(res)) return R.err(res.error);
+    const sections: string[] = [];
+    if (res.value.schema !== undefined) {
+      sections.push(dialect.schemaPrelude(res.value.schema));
+    }
+    const preludeSeen = new Set<string>();
+    for (const p of res.value.prelude) {
+      if (!preludeSeen.has(p.sql)) {
+        preludeSeen.add(p.sql);
+        sections.push(p.sql);
+      }
+    }
+    sections.push(res.value.sql);
+    return R.ok(sections.join("\n\n"));
+  }
+  if (shape.type === "module") {
+    const errors: string[] = [];
+    const results: TableResult[] = [];
+    for (const [tableKey, table] of Object.entries(shape.input)) {
+      const res = toSQLTable(table, dialect);
+      if (R.isOk(res)) results.push(res.value);
+      else errors.push(...res.error.map((e) => `table '${tableKey}': ${e}`));
+    }
+    if (errors.length > 0) return R.err(errors);
+
+    const sorted = topoSortTables(results);
+    if (!R.isOk(sorted)) return R.err(sorted.error);
+
+    const sections: string[] = [];
+    const schemasSeen = new Set<string>();
+    for (const t of sorted.value) {
+      if (t.schema !== undefined && !schemasSeen.has(t.schema)) {
+        schemasSeen.add(t.schema);
+        sections.push(dialect.schemaPrelude(t.schema));
+      }
+    }
+    const preludeSeen = new Set<string>();
+    for (const t of sorted.value) {
+      for (const p of t.prelude) {
+        if (!preludeSeen.has(p.sql)) {
+          preludeSeen.add(p.sql);
+          sections.push(p.sql);
+        }
+      }
+    }
+    for (const t of sorted.value) sections.push(t.sql);
+    return R.ok(sections.join("\n\n"));
+  }
+  return R.err(["toSQL expects a top-level mapping (table) or module"]);
+};

package/src/shape/transforms/typescript/index.ts

@@ -0,0 +1 @@
+export * from "./transform";

package/src/shape/transforms/typescript/transform.ts

@@ -0,0 +1,211 @@
+import { repeat } from "../../../common";
+import { shapes } from "../../shape";
+
+type Context = {
+  depth: number;
+  padding: number;
+};
+
+const incPadding = (ctx: Context): Context => ({
+  ...ctx,
+  padding: ctx.padding + 2,
+});
+const incDepth = (ctx: Context): Context => ({ ...ctx, depth: ctx.depth + 1 });
+const inc = (ctx: Context): Context => incPadding(incDepth(ctx));
+const mkpad = (n: number): string => repeat(" ", n);
+
+const getName = (shape: shapes.Shape): string | null => {
+  if (shape.anno.title && shape.anno.title.trim().length > 0)
+    return shape.anno.title;
+  const meta = shape.anno.meta;
+  if (!meta) return null;
+  const mTitle = meta["title"] || meta["name"];
+  if (mTitle && typeof mTitle === "string" && mTitle.trim().length > 0)
+    return mTitle;
+  return null;
+};
+
+const isSafeName = (x: string): boolean =>
+  !(x.includes(" ") || x.includes("-"));
+
+const autoQuote = (x: string): string => {
+  if (x.includes(" ") || x.includes("-")) return `"${x}"`;
+  return x;
+};
+
+const createComments = (shape: shapes.Shape): string[] => {
+  const comments: string[] = [];
+
+  if (shape.anno.description) {
+    comments.push(shape.anno.description);
+  }
+  if (shape.anno.comment) {
+    comments.push(shape.anno.comment);
+  }
+  if (shape.anno.primary) {
+    comments.push(`(primary)`);
+  }
+  if (shape.anno.pattern) {
+    comments.push(`must match pattern: ${shape.anno.pattern.toString()}`);
+  }
+  if (shape.anno.format) {
+    comments.push(`(format: ${shape.anno.format})`);
+  }
+  // Lift format from union members: a union of format-annotated strings
+  // collapses to `string` at the type level, but the formats themselves
+  // are useful to surface as a hint.
+  if (shape.type === "union" && !shape.anno.format) {
+    const formats = shape.input
+      .map((m) => m.anno.format)
+      .filter((f): f is string => typeof f === "string");
+    if (formats.length > 0 && formats.length === shape.input.length) {
+      comments.push(`(format: ${formats.join(" | ")})`);
+    }
+  }
+  if (typeof shape.anno.min === "number") {
+    comments.push(`must be >= ${shape.anno.min}`);
+  }
+  if (typeof shape.anno.max === "number") {
+    comments.push(`must be <= ${shape.anno.max}`);
+  }
+  if (shape.anno.foreign) {
+    comments.push(
+      `(foreign) references '${shape.anno.foreign.table}.${shape.anno.foreign.column}'`,
+    );
+  }
+  if (shape.anno.uniqueItems) {
+    comments.push(`(uniqueItems)`);
+  }
+  if (shape.anno.unique) {
+    comments.push(`(unique)`);
+  }
+  if (shape.anno.default) {
+    comments.push(`(default = ${shape.anno.default})`);
+  }
+
+  if (comments.length > 1) {
+    return ["/**", ...comments.map((x) => `* ${x}`), "**/"];
+  }
+
+  return comments.map((x) => `// ${x}`);
+};
+
+const renderComments = (comments: string[], pad: number): string => {
+  if (comments.length <= 0) return "";
+  return comments.map((x) => `${mkpad(pad)}${x}`).join("\n") + "\n";
+};
+
+const blockOfFields = (
+  rec: Record<string, shapes.Shape>,
+  ctx: Context,
+): string => {
+  return [
+    `{\n`,
+    Object.entries(rec)
+      .map(([field, s]) => {
+        const name = getName(s) || field;
+        return [
+          renderComments(createComments(s), ctx.padding + 2),
+          mkpad(ctx.padding + 2),
+          autoQuote(name),
+          s.anno.optional ? "?" : "",
+          ": ",
+          toTs(s, inc(ctx)),
+          ";",
+        ].join("");
+      })
+      .join("\n"),
+    `\n${mkpad(ctx.padding)}}`,
+  ].join("");
+};
+
+const listOfTypes = (
+  rec: Record<string, shapes.Shape>,
+  ctx: Context,
+): string => {
+  return [
+    Object.entries(rec)
+      .map(([field, s]) => {
+        const name = (getName(s) || field).replaceAll(" ", "_");
+        return [
+          renderComments(createComments(s), ctx.padding),
+          mkpad(ctx.padding),
+          `export type ${name} = `,
+          toTs(s, incDepth(ctx)),
+          `;`,
+        ].join("");
+      })
+      .join("\n"),
+  ].join("");
+};
+
+const toTs = (shape: shapes.Shape, ctx: Context): string => {
+  switch (shape.type) {
+    case "string":
+      if (shape.literal) return JSON.stringify(shape.input);
+      return shape.type;
+    case "number":
+    case "boolean":
+      if (shape.literal) return String(shape.input);
+      return shape.type;
+    case "undefined":
+    case "unknown":
+      return shape.type;
+    case "date":
+      return "Date";
+    case "nil":
+      return "null";
+    case "union": {
+      const parts = shape.input.map((x) => toTs(x, incDepth(ctx)));
+      return Array.from(new Set(parts)).join(" | ");
+    }
+    case "array":
+      return `Array<${toTs(shape.input, inc(ctx))}>`;
+    case "binary":
+      return `Uint8Array | Array<number>`;
+    case "vector":
+      return `Array<number>`;
+    case "tuple":
+      return `[${shape.input.map((s) => toTs(s, inc(ctx))).join(", ")}]`;
+    case "range": {
+      const item = toTs(shape.input, inc(ctx));
+      return `{ lower: ${item} | null; upper: ${item} | null; lowerInclusive: boolean; upperInclusive: boolean; }`;
+    }
+    case "record":
+      return `Record<${toTs(shape.input[0], incDepth(ctx))}, ${toTs(shape.input[1], inc(ctx))}>`;
+    case "module": {
+      const name = getName(shape);
+      if (name && isSafeName(name)) {
+        return [
+          `export namespace ${name} {\n`,
+          listOfTypes(shape.input, inc(ctx)),
+          `\n}`,
+        ].join("");
+      }
+      return listOfTypes(shape.input, ctx);
+    }
+    case "mapping": {
+      const name = getName(shape);
+      if (name && ctx.depth <= 0) {
+        const cleanName = name.replaceAll(/-| /g, "_");
+        return [
+          `export type ${cleanName} = `,
+          blockOfFields(shape.input, ctx),
+        ].join("");
+      }
+
+      return blockOfFields(shape.input, ctx);
+    }
+  }
+};
+
+export const toTypescript = (shape: shapes.Shape): string => {
+  const ctx: Context = {
+    depth: 0,
+    padding: 0,
+  };
+
+  const out = toTs(shape, ctx);
+
+  return out;
+};

package/src/shape/tuple.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, expectTypeOf } from "vitest";
+import { R } from "../common";
+import { B } from "./builder";
+import { shapes } from "./shape";
+import { toJSONSchema, fromJSONSchema } from "./transforms/json-schema";
+import { toSQL } from "./transforms/sql";
+import { toTypescript } from "./transforms/typescript";
+
+describe("shapes.tuple — construction & types", (it) => {
+  it("constructs with shapes.tuple", () => {
+    const t = shapes.tuple(shapes.float32(), shapes.string(), shapes.boolean());
+    expect(t.type).toBe("tuple");
+    expect(t.input).toHaveLength(3);
+    expect(t.input[0]!.type).toBe("number");
+    expect(t.input[1]!.type).toBe("string");
+    expect(t.input[2]!.type).toBe("boolean");
+  });
+
+  it("constructs with B.tuple (rest args)", () => {
+    const t = B.tuple(B.float32(), B.float32(), B.float32());
+    expect(t.shape.type).toBe("tuple");
+    expect(t.shape.input).toHaveLength(3);
+  });
+
+  it("constructs with B.tuple (array form)", () => {
+    const t = B.tuple([B.string(), B.number()] as const);
+    expect(t.shape.type).toBe("tuple");
+    expect(t.shape.input).toHaveLength(2);
+  });
+
+  it("infers a positional tuple output type", () => {
+    const t = shapes.tuple(shapes.float32(), shapes.string(), shapes.boolean());
+    expectTypeOf<shapes.InferShapeOut<typeof t>>().toEqualTypeOf<
+      [number, string, boolean]
+    >();
+  });
+
+  it("supports an empty tuple", () => {
+    const t = shapes.tuple();
+    expect(t.input).toEqual([]);
+    expect(shapes.validate(t, [])).toEqual([]);
+  });
+});
+
+describe("shapes.validate — tuple", (it) => {
+  it("accepts an array of matching length and element types", () => {
+    const t = shapes.tuple(
+      shapes.float32(),
+      shapes.float32(),
+      shapes.float32(),
+    );
+    expect(shapes.validate(t, [1.5, 2.5, 3.5])).toEqual([]);
+  });
+
+  it("rejects a non-array input", () => {
+    const t = shapes.tuple(shapes.string(), shapes.number());
+    const errors = shapes.validate(t, "not an array");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/tuple/);
+  });
+
+  it("rejects a length mismatch", () => {
+    const t = shapes.tuple(shapes.string(), shapes.number());
+    const errors = shapes.validate(t, ["a"]);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/length/);
+  });
+
+  it("reports the index of a type-mismatched position", () => {
+    const t = shapes.tuple(shapes.string(), shapes.number(), shapes.boolean());
+    const errors = shapes.validate(t, ["a", "not a number", true]);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]!.path).toEqual([1]);
+  });
+
+  it("validates heterogeneous element types independently", () => {
+    const t = shapes.tuple(shapes.string(), shapes.number(), shapes.boolean());
+    expect(shapes.validate(t, ["hi", 42, false])).toEqual([]);
+    expect(shapes.validate(t, [1, "x", false]).length).toBeGreaterThan(0);
+  });
+});
+
+describe("B.tuple — builder API", (it) => {
+  it(".is() narrows the input correctly", () => {
+    const t = B.tuple(B.float32(), B.float32(), B.float32());
+    const v: unknown = [1.5, 2.5, 3.5];
+    if (t.is(v)) {
+      expectTypeOf<typeof v>().toEqualTypeOf<[number, number, number]>();
+    }
+    expect(t.is([1.5, 2.5, 3.5])).toBe(true);
+    expect(t.is([1.5, 2.5])).toBe(false);
+  });
+
+  it(".parse() returns a Result", () => {
+    const t = B.tuple(B.string(), B.number());
+    const ok = t.parse(["x", 1]);
+    expect(R.isOk(ok)).toBe(true);
+    const err = t.parse(["x"]);
+    expect(R.isErr(err)).toBe(true);
+  });
+});
+
+describe("toJSONSchema / fromJSONSchema — tuple", (it) => {
+  it("emits prefixItems with min/max items and tuple meta", () => {
+    const t = shapes.tuple(shapes.string(), shapes.number());
+    const js = toJSONSchema(t);
+    expect(js.type).toBe("array");
+    expect(Array.isArray(js.prefixItems)).toBe(true);
+    expect(js.prefixItems).toHaveLength(2);
+    expect(js.minItems).toBe(2);
+    expect(js.maxItems).toBe(2);
+    expect(js["x-shapecraft"]?.kind).toBe("tuple");
+    expect(js["x-shapecraft"]?.tupleLen).toBe(2);
+  });
+
+  it("round-trips through fromJSONSchema", () => {
+    const t = shapes.tuple(shapes.string(), shapes.float32(), shapes.boolean());
+    const round = fromJSONSchema(toJSONSchema(t));
+    expect(round.type).toBe("tuple");
+    if (round.type !== "tuple") return;
+    expect(round.input).toHaveLength(3);
+    expect(round.input[0]!.type).toBe("string");
+    expect(round.input[1]!.type).toBe("number");
+    expect(round.input[2]!.type).toBe("boolean");
+  });
+
+  it("accepts legacy items: [...] form (length >= 2) as a tuple", () => {
+    const parsed = fromJSONSchema({
+      type: "array",
+      items: [{ type: "string" }, { type: "number" }],
+    });
+    expect(parsed.type).toBe("tuple");
+    if (parsed.type !== "tuple") return;
+    expect(parsed.input).toHaveLength(2);
+    expect(parsed.input[0]!.type).toBe("string");
+    expect(parsed.input[1]!.type).toBe("number");
+  });
+});
+
+describe("toSQL — tuple", (it) => {
+  it("emits jsonb with a length CHECK on a tuple column", () => {
+    const table = shapes.mapping({
+      id: { ...shapes.uint64(), anno: { primary: true } } as shapes.Shape,
+      coords: shapes.tuple(shapes.float32(), shapes.float32()),
+    });
+    const titled: shapes.ShapeMapping = {
+      ...table,
+      anno: { ...table.anno, title: "thing" },
+    };
+    const res = toSQL(titled);
+    expect(R.isOk(res)).toBe(true);
+    if (!R.isOk(res)) return;
+    expect(res.value).toMatch(/"coords" jsonb/);
+    expect(res.value).toMatch(/jsonb_array_length\("coords"\) = 2/);
+  });
+});
+
+describe("toTypescript — tuple", (it) => {
+  it("renders as [T1, T2, T3]", () => {
+    const t = shapes.tuple(shapes.string(), shapes.number(), shapes.boolean());
+    expect(toTypescript(t)).toBe("[string, number, boolean]");
+  });
+
+  it("renders nested tuples", () => {
+    const t = shapes.tuple(
+      shapes.tuple(shapes.float32(), shapes.float32()),
+      shapes.string(),
+    );
+    expect(toTypescript(t)).toBe("[[number, number], string]");
+  });
+});