shapedef 1.0.0

package/src/shape.ts

@@ -0,0 +1,488 @@
+import { has, isPlainObject } from "./common";
+import { Prettify, TupleOf } from "./common/types";
+import { Phantom, PhantomIgnore } from "./phantom";
+
+export const ShapeBrandSymbol = Symbol("Shape");
+export type ShapeBrandSymbol = typeof ShapeBrandSymbol;
+
+export type ShapeAnnotation = {
+  name?: string;
+  title?: string;
+  description?: string;
+  optional?: boolean;
+  primary?: boolean;
+  unique?: boolean;
+  min?: number;
+  max?: number;
+  format?: string;
+  pattern?: string;
+  uniqueWithin?: boolean;
+  defaultValue?: any;
+  foreign?: {
+    shapeName: string;
+    fieldName: string;
+  };
+};
+
+export type PhantomShape = {
+  out: any;
+};
+
+export type LooseShape = {
+  type: string;
+  __phantom: PhantomShape;
+  anno: ShapeAnnotation;
+};
+
+export type OutputOfShape<T> =
+  [T] extends [LooseShape] ? T["__phantom"]["out"] : never;
+
+export type AnnoOfShape<T> = [T] extends [LooseShape] ? T["anno"] : never;
+
+export type ShapeIsOptional<T> =
+  [AnnoOfShape<T>["optional"]] extends [true] ? true : false;
+
+export type AnnotateShape<
+  T extends LooseShape,
+  Anno extends ShapeAnnotation,
+> = T & { anno: T["anno"] & Anno };
+
+export interface ShapeBase<Type extends string> extends LooseShape {
+  type: Type;
+  [ShapeBrandSymbol]: true;
+}
+
+export interface ShapeWithOutput<
+  Type extends string,
+  Out,
+> extends ShapeBase<Type> {
+  __phantom: { out: Out };
+}
+
+export interface ShapeFloat extends ShapeWithOutput<"float", number> {}
+export interface ShapeInt extends ShapeWithOutput<"int", number> {}
+export interface ShapeNumber extends ShapeWithOutput<"number", number> {}
+export interface ShapeBool extends ShapeWithOutput<"bool", boolean> {}
+export interface ShapeStr extends ShapeWithOutput<"str", string> {}
+export interface ShapeDate extends ShapeWithOutput<"date", Date> {}
+export interface ShapeNil extends ShapeWithOutput<"nil", null> {}
+export interface ShapeUnknown extends ShapeWithOutput<"unknown", unknown> {}
+
+export interface ShapeLiteralFloat<
+  Value extends number = number,
+> extends ShapeWithOutput<"literal-float", Value> {
+  value: Value;
+}
+export interface ShapeLiteralInt<
+  Value extends number = number,
+> extends ShapeWithOutput<"literal-int", Value> {
+  value: Value;
+}
+export interface ShapeLiteralNumber<
+  Value extends number = number,
+> extends ShapeWithOutput<"literal-number", Value> {
+  value: Value;
+}
+export interface ShapeLiteralBool<
+  Value extends boolean = boolean,
+> extends ShapeWithOutput<"literal-bool", Value> {
+  value: Value;
+}
+export interface ShapeLiteralStr<
+  Value extends string = string,
+> extends ShapeWithOutput<"literal-str", Value> {
+  value: Value;
+}
+
+export interface ShapeRef<
+  Name extends string = string,
+  Hint extends Shape = ShapeUnknown,
+> extends ShapeBase<"ref"> {
+  name: Name;
+  hint?: Hint;
+  __phantom: { out: unknown };
+}
+
+export interface ShapeArray<
+  Item extends Shape = Shape,
+> extends ShapeBase<"array"> {
+  item: Item;
+  __phantom: { out: Array<OutputOfShape<Item>> };
+}
+
+export interface ShapeTuple<
+  out Items extends TupleOf<Shape> = TupleOf<Shape>,
+> extends ShapeBase<"tuple"> {
+  tup: Items;
+  __phantom: { out: { -readonly [P in keyof Items]: Items[P] } };
+}
+
+export interface ShapeMapping<
+  Rec extends Record<string, Shape> = Record<string, Shape>,
+> extends ShapeBase<"mapping"> {
+  rec: Rec;
+  __phantom: {
+    out: Prettify<
+      {
+        -readonly [P in keyof Rec as [ShapeIsOptional<Rec[P]>] extends [true] ?
+          never
+        : P]: OutputOfShape<Rec[P]>;
+      } & {
+        -readonly [P in keyof Rec as [ShapeIsOptional<Rec[P]>] extends [true] ?
+          P
+        : never]?: OutputOfShape<Rec[P]>;
+      }
+    >;
+  };
+}
+
+export interface ShapeVector<
+  Dims extends number = number,
+> extends ShapeWithOutput<"vector", number[]> {
+  dims: Dims;
+}
+
+export interface ShapeUnion<
+  out Ofs extends TupleOf<Shape> | Array<Shape> = TupleOf<Shape> | Array<Shape>,
+> extends ShapeWithOutput<"union", OutputOfShape<Ofs[number]>> {
+  ofs: Ofs;
+}
+
+export type Shape =
+  | ShapeFloat
+  | ShapeInt
+  | ShapeNumber
+  | ShapeBool
+  | ShapeStr
+  | ShapeDate
+  | ShapeNil
+  | ShapeUnknown
+  | ShapeLiteralFloat
+  | ShapeLiteralInt
+  | ShapeLiteralNumber
+  | ShapeLiteralBool
+  | ShapeLiteralStr
+  | ShapeRef
+  | ShapeArray
+  | ShapeMapping
+  | ShapeTuple
+  | ShapeVector
+  | ShapeUnion;
+
+const createPhantom = (): {
+  __phantom: { out: PhantomIgnore };
+  [ShapeBrandSymbol]: true;
+} => {
+  return { __phantom: { out: Phantom }, [ShapeBrandSymbol]: true };
+};
+
+export function isShape(x: unknown): x is Shape {
+  return (
+    has(x, ShapeBrandSymbol) &&
+    (x as { [ShapeBrandSymbol]: unknown })[ShapeBrandSymbol] === true
+  );
+}
+
+export namespace shapes {
+  export function float(): ShapeFloat {
+    return {
+      type: "float",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function int(): ShapeInt {
+    return {
+      type: "int",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function number(): ShapeNumber {
+    return {
+      type: "number",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function bool(): ShapeBool {
+    return {
+      type: "bool",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function str(): ShapeStr {
+    return {
+      type: "str",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function date(): ShapeDate {
+    return {
+      type: "date",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function nil(): ShapeNil {
+    return {
+      type: "nil",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function unknown(): ShapeUnknown {
+    return {
+      type: "unknown",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function literalFloat<Value extends number>(
+    value: Value,
+  ): ShapeLiteralFloat<Value> {
+    return {
+      type: "literal-float",
+      value: value,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function literalInt<Value extends number>(
+    value: Value,
+  ): ShapeLiteralInt<Value> {
+    return {
+      type: "literal-int",
+      value: value,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function literalNumber<Value extends number>(
+    value: Value,
+  ): ShapeLiteralNumber<Value> {
+    return {
+      type: "literal-number",
+      value: value,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function literalBool<Value extends boolean>(
+    value: Value,
+  ): ShapeLiteralBool<Value> {
+    return {
+      type: "literal-bool",
+      value: value,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function literalStr<Value extends string>(
+    value: Value,
+  ): ShapeLiteralStr<Value> {
+    return {
+      type: "literal-str",
+      value: value,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function literal<Value extends number>(
+    value: Value,
+  ): ShapeLiteralNumber<Value>;
+  export function literal<Value extends boolean>(
+    value: Value,
+  ): ShapeLiteralBool<Value>;
+  export function literal<Value extends string>(
+    value: Value,
+  ): ShapeLiteralStr<Value>;
+  export function literal(
+    value: number | boolean | string,
+  ): ShapeLiteralNumber | ShapeLiteralBool | ShapeLiteralStr;
+  export function literal(
+    value: number | boolean | string,
+  ): ShapeLiteralNumber | ShapeLiteralBool | ShapeLiteralStr {
+    if (typeof value === "number") return literalNumber(value);
+    if (typeof value === "boolean") return literalBool(value);
+    return literalStr(value);
+  }
+
+  export function ref<Name extends string, Hint extends Shape = ShapeUnknown>(
+    name: Name,
+    hint?: Hint,
+  ): ShapeRef<Name, Hint> {
+    return {
+      type: "ref",
+      name: name,
+      anno: {},
+      ...(hint ?
+        {
+          hint: hint,
+        }
+      : {}),
+      ...createPhantom(),
+    };
+  }
+
+  export function array<Item extends Shape>(item: Item): ShapeArray<Item> {
+    return {
+      type: "array",
+      item: item,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function tuple<Items extends TupleOf<Shape>>(
+    ...items: Items
+  ): ShapeTuple<Items> {
+    return {
+      type: "tuple",
+      tup: items,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function mapping<Rec extends Record<string, Shape>>(
+    rec: Rec,
+  ): ShapeMapping<Rec> {
+    return {
+      type: "mapping",
+      rec: rec,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function vector<Dims extends number>(dims: Dims): ShapeVector<Dims> {
+    return {
+      type: "vector",
+      dims: dims,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
+  export function union<Ofs extends Array<Shape>>(...ofs: Ofs): ShapeUnion<Ofs>;
+  export function union<Ofs extends TupleOf<Shape>>(
+    ...ofs: Ofs
+  ): ShapeUnion<Ofs>;
+  export function union<Ofs extends TupleOf<Shape>>(
+    ...ofs: Ofs
+  ): ShapeUnion<Ofs> {
+    return {
+      type: "union",
+      ofs: ofs,
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+}
+
+export namespace annotate {
+  export function by<S extends Shape, Anno extends ShapeAnnotation>(
+    shape: S,
+    anno: Anno,
+  ): AnnotateShape<S, Anno> {
+    return {
+      ...shape,
+      anno: {
+        ...anno,
+        ...shape.anno,
+      },
+    };
+  }
+
+  export function optional<S extends Shape>(
+    shape: S,
+  ): AnnotateShape<S, { optional: true }> {
+    return by(shape, { optional: true });
+  }
+
+  export function primary<S extends Shape>(
+    shape: S,
+  ): AnnotateShape<S, { primary: true }> {
+    return by(shape, { primary: true });
+  }
+
+  export function unique<S extends Shape>(
+    shape: S,
+  ): AnnotateShape<S, { unique: true }> {
+    return by(shape, { unique: true });
+  }
+
+  export function named<S extends Shape, Name extends string>(
+    shape: S,
+    name: Name,
+  ): AnnotateShape<S, { name: Name }> {
+    return by(shape, { name: name });
+  }
+
+  export function foreign<
+    S extends Shape,
+    ShapeName extends string,
+    FieldName extends string,
+  >(
+    shape: S,
+    shapeName: ShapeName,
+    fieldName: FieldName,
+  ): AnnotateShape<
+    S,
+    { foreign: { shapeName: ShapeName; fieldName: FieldName } }
+  > {
+    return by(shape, { foreign: { shapeName, fieldName } });
+  }
+
+  export function auto(
+    x: unknown,
+    options: {
+      preferLiterals?: boolean;
+    } = {},
+  ): Shape {
+    if (isShape(x)) return x;
+    if (x === null) return shapes.nil();
+    if (typeof x === "undefined") return shapes.unknown();
+    if (typeof x === "number")
+      return options.preferLiterals ? shapes.literalNumber(x) : shapes.number();
+    if (typeof x === "string")
+      return options.preferLiterals ? shapes.literalStr(x) : shapes.str();
+    if (typeof x === "boolean")
+      return options.preferLiterals ? shapes.literalBool(x) : shapes.bool();
+    if (x instanceof Date) return shapes.date();
+    if (Array.isArray(x)) {
+      if (x.length <= 0) return shapes.array(shapes.unknown());
+      if (x.length === 1) return shapes.array(auto(x[0], options));
+      const types = new Set(x.map((v) => typeof v));
+      return shapes.array(
+        types.size === 1 ?
+          auto(x[0], options)
+        : shapes.union(...x.map((v) => auto(v, options))),
+      );
+    }
+    if (isPlainObject(x)) {
+      return shapes.mapping(
+        Object.fromEntries(
+          Object.entries(x).map(([k, v]) => [k, auto(v, options)]),
+        ),
+      );
+    }
+    return shapes.unknown();
+  }
+}

package/src/translations/index.ts

@@ -0,0 +1,3 @@
+export * from "./translation";
+export * from "./typescript";
+export * from "./postgres";

package/src/translations/postgres.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect } from "vitest";
+import { annotate, shapes } from "../shape";
+import { postgres } from "./postgres";
+
+describe("postgres", (it) => {
+  it("translates primitive types", () => {
+    expect(postgres(shapes.int())).toBe("INTEGER");
+    expect(postgres(shapes.float())).toBe("DOUBLE PRECISION");
+    expect(postgres(shapes.number())).toBe("NUMERIC");
+    expect(postgres(shapes.bool())).toBe("BOOLEAN");
+    expect(postgres(shapes.str())).toBe("TEXT");
+    expect(postgres(shapes.date())).toBe("TIMESTAMPTZ");
+    expect(postgres(shapes.nil())).toBe("NULL");
+    expect(postgres(shapes.unknown())).toBe("JSONB");
+  });
+
+  it("translates vector type (pgvector)", () => {
+    expect(postgres(shapes.vector(300))).toBe("vector(300)");
+    expect(postgres(shapes.vector(1536))).toBe("vector(1536)");
+  });
+
+  it("translates arrays of primitives to native PG array types", () => {
+    expect(postgres(shapes.array(shapes.str()))).toBe("TEXT[]");
+    expect(postgres(shapes.array(shapes.int()))).toBe("INTEGER[]");
+    expect(postgres(shapes.array(shapes.float()))).toBe("DOUBLE PRECISION[]");
+    expect(postgres(shapes.array(shapes.number()))).toBe("NUMERIC[]");
+    expect(postgres(shapes.array(shapes.bool()))).toBe("BOOLEAN[]");
+    expect(postgres(shapes.array(shapes.date()))).toBe("TIMESTAMPTZ[]");
+    expect(postgres(shapes.array(shapes.vector(3)))).toBe("vector(3)[]");
+  });
+
+  it("translates multi-dimensional arrays", () => {
+    expect(postgres(shapes.array(shapes.array(shapes.int())))).toBe(
+      "INTEGER[][]",
+    );
+  });
+
+  it("falls back to JSONB for arrays of complex types", () => {
+    expect(
+      postgres(shapes.array(shapes.union(shapes.int(), shapes.str()))),
+    ).toBe("JSONB");
+    expect(postgres(shapes.array(shapes.mapping({ x: shapes.int() })))).toBe(
+      "JSONB",
+    );
+  });
+
+  it("translates other composite types to JSONB", () => {
+    expect(postgres(shapes.tuple(shapes.int(), shapes.str()))).toBe("JSONB");
+    expect(postgres(shapes.union(shapes.int(), shapes.str()))).toBe("JSONB");
+    expect(postgres(shapes.mapping({ x: shapes.int() }))).toBe("JSONB");
+  });
+
+  it("generates CREATE TABLE IF NOT EXISTS for named mappings", () => {
+    expect(
+      postgres(
+        annotate.named(
+          shapes.mapping({
+            id: annotate.primary(shapes.int()),
+            name: shapes.str(),
+          }),
+          "User",
+        ),
+      ),
+    ).toBe(
+      [
+        "CREATE TABLE IF NOT EXISTS User (",
+        "  id INTEGER PRIMARY KEY,",
+        "  name TEXT NOT NULL",
+        ")",
+      ].join("\n"),
+    );
+  });
+
+  it("generates CREATE TABLE IF NOT EXISTS with vector column", () => {
+    expect(
+      postgres(
+        annotate.named(
+          shapes.mapping({
+            id: annotate.primary(shapes.int()),
+            my_embedding: shapes.vector(300),
+          }),
+          "Foobar",
+        ),
+      ),
+    ).toBe(
+      [
+        "CREATE TABLE IF NOT EXISTS Foobar (",
+        "  id INTEGER PRIMARY KEY,",
+        "  my_embedding vector(300) NOT NULL",
+        ")",
+      ].join("\n"),
+    );
+  });
+
+  it("marks optional columns as nullable (no NOT NULL)", () => {
+    expect(
+      postgres(
+        annotate.named(
+          shapes.mapping({
+            id: annotate.primary(shapes.int()),
+            nickname: annotate.optional(shapes.str()),
+          }),
+          "Profile",
+        ),
+      ),
+    ).toBe(
+      [
+        "CREATE TABLE IF NOT EXISTS Profile (",
+        "  id INTEGER PRIMARY KEY,",
+        "  nickname TEXT",
+        ")",
+      ].join("\n"),
+    );
+  });
+
+  it("adds UNIQUE constraint", () => {
+    expect(
+      postgres(
+        annotate.named(
+          shapes.mapping({
+            id: annotate.primary(shapes.int()),
+            email: annotate.unique(shapes.str()),
+          }),
+          "Account",
+        ),
+      ),
+    ).toBe(
+      [
+        "CREATE TABLE IF NOT EXISTS Account (",
+        "  id INTEGER PRIMARY KEY,",
+        "  email TEXT NOT NULL UNIQUE",
+        ")",
+      ].join("\n"),
+    );
+  });
+
+  it("adds REFERENCES for foreign key columns", () => {
+    expect(
+      postgres(
+        annotate.named(
+          shapes.mapping({
+            id: annotate.primary(shapes.int()),
+            user_id: annotate.foreign(shapes.int(), "User", "id"),
+          }),
+          "Post",
+        ),
+      ),
+    ).toBe(
+      [
+        "CREATE TABLE IF NOT EXISTS Post (",
+        "  id INTEGER PRIMARY KEY,",
+        "  user_id INTEGER NOT NULL REFERENCES User(id)",
+        ")",
+      ].join("\n"),
+    );
+  });
+
+  it("returns column type for unnamed mappings", () => {
+    expect(postgres(shapes.mapping({ x: shapes.int() }))).toBe("JSONB");
+  });
+});

package/src/translations/postgres.ts

@@ -0,0 +1,73 @@
+import { Shape } from "../shape";
+import { TranslationFunc } from "./translation";
+
+const pgType = (shape: Shape): string => {
+  switch (shape.type) {
+    case "int":
+      return "INTEGER";
+    case "float":
+      return "DOUBLE PRECISION";
+    case "number":
+      return "NUMERIC";
+    case "str":
+      return "TEXT";
+    case "bool":
+      return "BOOLEAN";
+    case "date":
+      return "TIMESTAMPTZ";
+    case "nil":
+      return "NULL";
+    case "unknown":
+      return "JSONB";
+    case "literal-int":
+    case "literal-float":
+    case "literal-number":
+      return "NUMERIC";
+    case "literal-str":
+      return "TEXT";
+    case "literal-bool":
+      return "BOOLEAN";
+    case "ref":
+      return shape.name;
+    case "array": {
+      const inner = pgType(shape.item);
+      return inner === "JSONB" ? "JSONB" : `${inner}[]`;
+    }
+    case "tuple":
+      return "JSONB";
+    case "union":
+      return "JSONB";
+    case "vector":
+      return `vector(${shape.dims})`;
+    case "mapping":
+      return "JSONB";
+  }
+};
+
+const pgColumnDef = (colName: string, shape: Shape): string => {
+  const parts: string[] = [colName, pgType(shape)];
+  if (shape.anno.primary) {
+    parts.push("PRIMARY KEY");
+  } else if (!shape.anno.optional) {
+    parts.push("NOT NULL");
+  }
+  if (shape.anno.unique && !shape.anno.primary) {
+    parts.push("UNIQUE");
+  }
+  if (shape.anno.foreign) {
+    parts.push(
+      `REFERENCES ${shape.anno.foreign.shapeName}(${shape.anno.foreign.fieldName})`,
+    );
+  }
+  return parts.join(" ");
+};
+
+export const postgres: TranslationFunc<string> = (shape) => {
+  if (shape.type === "mapping" && shape.anno.name) {
+    const cols = Object.entries(shape.rec)
+      .map(([k, v]) => `  ${pgColumnDef(k, v)}`)
+      .join(",\n");
+    return `CREATE TABLE IF NOT EXISTS ${shape.anno.name} (\n${cols}\n)`;
+  }
+  return pgType(shape);
+};