shapedef 1.0.0

package/src/common/guards.ts

@@ -0,0 +1,23 @@
+export const isPlainObject = (x: any): x is Record<PropertyKey, unknown> => {
+  if (x === null || typeof x === "undefined") return false;
+  if (Array.isArray(x)) return false;
+  if (x instanceof Date) return false;
+  return Object.getPrototypeOf(x) === Object.prototype;
+};
+
+export function has<Keys extends [...PropertyKey[]]>(
+  x: unknown,
+  ...keys: Keys
+): x is {
+  [Prop in keyof Keys as [Keys[Prop]] extends [string] ? Keys[Prop]
+  : never]: unknown;
+} {
+  if (typeof x === "undefined" || x === null) return false;
+  if (
+    keys.every(
+      (key) => Object.hasOwn(x, key) || (typeof x === "object" && key in x),
+    )
+  )
+    return true;
+  return false;
+}

package/src/common/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./guards";

package/src/common/padding.ts

@@ -0,0 +1,6 @@
+export const mkpad = (n: number, fill: string = " "): string =>
+  n <= 0 ? "" : (
+    Array.from(Array(n).keys())
+      .map(() => fill)
+      .join("")
+  );

package/src/common/types.ts

@@ -0,0 +1,21 @@
+export type TupleOf<T> = [T, ...T[]] | [...T[], T] | [T];
+
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+export type UnionToIntersection<union> =
+  (union extends any ? (k: union) => void : never) extends (
+    (k: infer intersection) => void
+  ) ?
+    intersection
+  : never;
+
+export type IsUnion<a> = [a] extends [UnionToIntersection<a>] ? false : true;
+
+export type UnionToTuple<union, output extends any[] = []> =
+  UnionToIntersection<union extends any ? (t: union) => union : never> extends (
+    (_: any) => infer elem
+  ) ?
+    UnionToTuple<Exclude<union, elem>, [elem, ...output]>
+  : output;

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./shape";
+export * from "./shape-utils";
+export * from "./inputs";
+export * from "./translations";

package/src/inputs/index.ts

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

package/src/inputs/json-schema.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect } from "vitest";
+import { fromJSONSchema } from "./json-schema";
+
+describe("fromJSONSchema", (it) => {
+  it("translates primitive types", () => {
+    expect(fromJSONSchema({ type: "string" })).toMatchObject({ type: "str" });
+    expect(fromJSONSchema({ type: "number" })).toMatchObject({ type: "float" });
+    expect(fromJSONSchema({ type: "integer" })).toMatchObject({ type: "int" });
+    expect(fromJSONSchema({ type: "boolean" })).toMatchObject({ type: "bool" });
+    expect(fromJSONSchema({ type: "null" })).toMatchObject({ type: "nil" });
+  });
+
+  it("translates date-like types", () => {
+    expect(fromJSONSchema({ type: "date" })).toMatchObject({ type: "date" });
+    expect(fromJSONSchema({ type: "datetime" })).toMatchObject({
+      type: "date",
+    });
+    expect(fromJSONSchema({ type: "date-time" })).toMatchObject({
+      type: "date",
+    });
+    expect(fromJSONSchema({ type: "timestamp" })).toMatchObject({
+      type: "date",
+    });
+    expect(fromJSONSchema({ type: "timestamptz" })).toMatchObject({
+      type: "date",
+    });
+  });
+
+  it("translates array type with items", () => {
+    const result = fromJSONSchema({ type: "array", items: { type: "string" } });
+    expect(result).toMatchObject({ type: "array" });
+    expect((result as any).item).toMatchObject({ type: "str" });
+  });
+
+  it("translates array type without items to array of unknown", () => {
+    const result = fromJSONSchema({ type: "array" });
+    expect(result).toMatchObject({ type: "array" });
+    expect((result as any).item).toMatchObject({ type: "unknown" });
+  });
+
+  it("translates object type with properties", () => {
+    const result = fromJSONSchema({
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "integer" },
+      },
+      required: ["name"],
+    });
+    expect(result).toMatchObject({ type: "mapping" });
+    const rec = (result as any).rec;
+    expect(rec.name).toMatchObject({ type: "str" });
+    expect(rec.name.anno.optional).toBeUndefined();
+    expect(rec.age).toMatchObject({ type: "int" });
+    expect(rec.age.anno.optional).toBe(true);
+  });
+
+  it("translates object type without properties to empty mapping", () => {
+    const result = fromJSONSchema({ type: "object" });
+    expect(result).toMatchObject({ type: "mapping", rec: {} });
+  });
+
+  it("treats all properties as optional when required array is absent", () => {
+    const result = fromJSONSchema({
+      type: "object",
+      properties: { id: { type: "integer" } },
+    });
+    expect((result as any).rec.id.anno.optional).toBe(true);
+  });
+
+  it("translates const string", () => {
+    expect(fromJSONSchema({ const: "hello" })).toMatchObject({
+      type: "literal-str",
+      value: "hello",
+    });
+  });
+
+  it("translates const boolean", () => {
+    expect(fromJSONSchema({ const: true })).toMatchObject({
+      type: "literal-bool",
+      value: true,
+    });
+  });
+
+  it("translates const number with integer type", () => {
+    expect(fromJSONSchema({ type: "integer", const: 1 })).toMatchObject({
+      type: "literal-int",
+      value: 1,
+    });
+  });
+
+  it("translates const number with float type", () => {
+    expect(fromJSONSchema({ type: "number", const: 1.5 })).toMatchObject({
+      type: "literal-float",
+      value: 1.5,
+    });
+  });
+
+  it("translates const number without numeric type to literal-number", () => {
+    expect(fromJSONSchema({ const: 42 })).toMatchObject({
+      type: "literal-number",
+      value: 42,
+    });
+  });
+
+  it("translates oneOf to union", () => {
+    const result = fromJSONSchema({
+      oneOf: [{ type: "string" }, { type: "integer" }],
+    });
+    expect(result).toMatchObject({ type: "union" });
+    const ofs = (result as any).ofs;
+    expect(ofs).toHaveLength(2);
+    expect(ofs[0]).toMatchObject({ type: "str" });
+    expect(ofs[1]).toMatchObject({ type: "int" });
+  });
+
+  it("translates anyOf to union", () => {
+    const result = fromJSONSchema({
+      anyOf: [{ type: "string" }, { type: "null" }],
+    });
+    expect(result).toMatchObject({ type: "union" });
+    const ofs = (result as any).ofs;
+    expect(ofs[0]).toMatchObject({ type: "str" });
+    expect(ofs[1]).toMatchObject({ type: "nil" });
+  });
+
+  it("annotates title", () => {
+    const result = fromJSONSchema({ type: "string", title: "Full Name" });
+    expect(result.anno.title).toBe("Full Name");
+  });
+
+  it("annotates name", () => {
+    const result = fromJSONSchema({ type: "string", name: "fullName" });
+    expect(result.anno.name).toBe("fullName");
+  });
+
+  it("annotates description", () => {
+    const result = fromJSONSchema({ type: "string", description: "A name" });
+    expect(result.anno.description).toBe("A name");
+  });
+
+  it("annotates minimum and maximum", () => {
+    const result = fromJSONSchema({ type: "number", minimum: 0, maximum: 100 });
+    expect(result.anno.min).toBe(0);
+    expect(result.anno.max).toBe(100);
+  });
+
+  it("annotates minLength and maxLength", () => {
+    const result = fromJSONSchema({
+      type: "string",
+      minLength: 1,
+      maxLength: 50,
+    });
+    expect(result.anno.min).toBe(1);
+    expect(result.anno.max).toBe(50);
+  });
+
+  it("annotates minItems and maxItems", () => {
+    const result = fromJSONSchema({
+      type: "array",
+      items: { type: "string" },
+      minItems: 2,
+      maxItems: 10,
+    });
+    expect(result.anno.min).toBe(2);
+    expect(result.anno.max).toBe(10);
+  });
+
+  it("handles unknown type string gracefully", () => {
+    expect(fromJSONSchema({ type: "nope" })).toMatchObject({ type: "unknown" });
+  });
+
+  it("handles nested objects", () => {
+    const result = fromJSONSchema({
+      type: "object",
+      properties: {
+        address: {
+          type: "object",
+          properties: { city: { type: "string" } },
+          required: ["city"],
+        },
+      },
+      required: ["address"],
+    });
+    expect(result).toMatchObject({ type: "mapping" });
+    const addressShape = (result as any).rec.address;
+    expect(addressShape).toMatchObject({ type: "mapping" });
+    expect(addressShape.rec.city).toMatchObject({ type: "str" });
+    expect(addressShape.rec.city.anno.optional).toBeUndefined();
+  });
+});

package/src/inputs/json-schema.ts

@@ -0,0 +1,324 @@
+import { has, isPlainObject } from "../common";
+import { annotate, Shape, shapes } from "../shape";
+
+const fromObject = (schema: unknown): Shape => {
+  const properties: Record<string, Shape> = {};
+
+  for (const propertiesKey of ["properties", "patternProperties"]) {
+    if (has(schema, propertiesKey)) {
+      const props = schema[propertiesKey];
+      if (isPlainObject(props)) {
+        let required: string[] = [];
+        if (has(schema, "required")) {
+          if (Array.isArray(schema.required)) {
+            if (schema.required.every((x) => typeof x === "string")) {
+              required = schema.required;
+            }
+          }
+        }
+        for (const [k, v] of Object.entries(props)) {
+          let s = fromJSONSchema(v);
+
+          if (!required.includes(k)) {
+            s = annotate.optional(s);
+          }
+
+          const key = k.match(/\^(.*?)\$/g) || k.match(/^[0-9]/) ? `'${k}'` : k;
+
+          properties[key] = s;
+        }
+      }
+    }
+  }
+
+  return shapes.mapping(properties);
+};
+
+export const fromJSONSchema = (
+  schema: unknown,
+  hint?: Shape,
+  typenameOverride?: string,
+): Shape => {
+  if (typeof schema === "string") return shapes.literal(schema);
+  if (typeof schema === "number") return shapes.literal(schema);
+  if (typeof schema === "boolean") return shapes.literal(schema);
+
+  if (!isPlainObject(schema)) return shapes.unknown();
+
+  const typename =
+    typenameOverride ||
+    (has(schema, "type") ? schema.type : "object") ||
+    "object";
+
+  let shape: Shape = shapes.unknown();
+
+  if (typeof typename === "string") {
+    switch (typename) {
+      case "vector":
+        {
+          const size =
+            has(schema, "size") ? Number(schema.size)
+            : has(schema, "dims") ? Number(schema.dims)
+            : has(schema, "dimensions") ? Number(schema.dimensions)
+            : 0;
+          shape = shapes.vector(size);
+        }
+        break;
+      case "date":
+        shape = shapes.date();
+        break;
+      case "datetime":
+        shape = shapes.date();
+        break;
+      case "date-time":
+        shape = shapes.date();
+        break;
+      case "timestamp":
+        shape = shapes.date();
+        break;
+      case "timestamptz":
+        shape = shapes.date();
+        break;
+      case "string":
+        shape = shapes.str();
+        break;
+      case "number":
+        shape = shapes.float();
+        break;
+      case "integer":
+        shape = shapes.int();
+        break;
+      case "boolean":
+        shape = shapes.bool();
+        break;
+      case "null":
+        shape = shapes.nil();
+        break;
+      case "object":
+        shape = fromObject(schema);
+        break;
+      case "array":
+        {
+          if (!has(schema, "items")) {
+            shape = shapes.array(shapes.unknown());
+            break;
+          }
+          const items = schema.items;
+          shape = shapes.array(fromJSONSchema(items));
+        }
+        break;
+      default:
+        {
+          /* noop */
+        }
+        break;
+    }
+  } else if (Array.isArray(typename)) {
+    const members: Shape[] = [];
+    if (typename.every((x) => typeof x === "string")) {
+      for (const subtype of typename) {
+        if (subtype === "null") {
+          members.push(shapes.nil());
+        } else if (subtype === "object") {
+          members.push(fromJSONSchema(schema, undefined, subtype));
+        } else if (subtype === "array") {
+          members.push(fromJSONSchema(schema, undefined, subtype));
+        } else if (subtype === "string") {
+          members.push(shapes.str());
+        } else if (subtype === "boolean") {
+          members.push(shapes.bool());
+        }
+      }
+    }
+    if (members.length === 1) {
+      shape = members[0]!;
+    } else if (members.length > 1) {
+      shape = shapes.union(...members);
+    }
+  }
+
+  const parsedType = shape.type;
+
+  if (has(schema, "const")) {
+    const lit = schema.const;
+    if (typeof lit === "string") {
+      shape = shapes.literalStr(lit);
+    } else if (typeof lit === "number") {
+      if (parsedType === "int") {
+        shape = shapes.literalInt(lit);
+      } else if (parsedType === "float") {
+        shape = shapes.literalFloat(lit);
+      } else {
+        shape = shapes.literalNumber(lit);
+      }
+    } else if (typeof lit === "boolean") {
+      shape = shapes.literalBool(lit);
+    }
+  }
+
+  if (has(schema, "$ref")) {
+    if (typeof schema.$ref === "string") {
+      shape = shapes.ref<string, any>(schema.$ref, shape);
+    }
+  }
+
+  if (has(schema, "oneOf")) {
+    if (Array.isArray(schema.oneOf)) {
+      const unionMembers: Shape[] = [];
+      if (shape.type === "mapping" && Object.keys(shape.rec).length > 0) {
+        unionMembers.push(shape);
+      }
+      unionMembers.push(...schema.oneOf.map((x) => fromJSONSchema(x, shape)));
+      shape = shapes.union(...unionMembers);
+    }
+  }
+  if (has(schema, "anyOf")) {
+    if (Array.isArray(schema.anyOf)) {
+      const unionMembers: Shape[] = [];
+      if (shape.type === "mapping" && Object.keys(shape.rec).length > 0) {
+        unionMembers.push(shape);
+      }
+      unionMembers.push(...schema.anyOf.map((x) => fromJSONSchema(x, shape)));
+      shape = shapes.union(...unionMembers);
+    }
+  }
+  if (has(schema, "enum")) {
+    if (Array.isArray(schema.enum)) {
+      if (schema.enum.length === 1) {
+        shape = fromJSONSchema(schema.enum[0]!);
+      } else {
+        shape = shapes.union(
+          ...schema.enum.map((x) => fromJSONSchema(x, shape)),
+        );
+      }
+    }
+  }
+
+  if (shape.type === "unknown" && hint) {
+    switch (hint.type) {
+      case "str":
+        shape = shapes.str();
+        break;
+      case "int":
+        shape = shapes.int();
+        break;
+      case "float":
+        shape = shapes.float();
+        break;
+      case "number":
+        shape = shapes.number();
+        break;
+      case "bool":
+        shape = shapes.bool();
+        break;
+      case "date":
+        shape = shapes.date();
+        break;
+      default:
+        {
+          /* noop */
+        }
+        break;
+    }
+  }
+
+  if (has(schema, "format")) {
+    if (typeof schema.format === "string") {
+      shape = annotate.by(shape, { format: schema.format });
+    }
+  }
+
+  if (has(schema, "pattern")) {
+    if (typeof schema.pattern === "string") {
+      shape = annotate.by(shape, { pattern: schema.pattern });
+    }
+  }
+
+  if (has(schema, "uniqueItems")) {
+    if (typeof schema.uniqueItems === "boolean") {
+      shape = annotate.by(shape, { uniqueWithin: schema.uniqueItems });
+    }
+  }
+
+  if (has(schema, "default")) {
+    shape = annotate.by(shape, { defaultValue: schema.default });
+  }
+
+  if (has(schema, "title")) {
+    if (typeof schema.title === "string") {
+      shape = annotate.by(shape, { title: schema.title });
+    }
+  }
+  if (has(schema, "name")) {
+    if (typeof schema.name === "string") {
+      shape = annotate.by(shape, { name: schema.name });
+    }
+  }
+  if (has(schema, "description")) {
+    if (typeof schema.description === "string") {
+      shape = annotate.by(shape, { description: schema.description });
+    }
+  }
+  if (has(schema, "minimum")) {
+    if (typeof schema.minimum === "number") {
+      shape = annotate.by(shape, { min: schema.minimum });
+    }
+  }
+  if (has(schema, "maximum")) {
+    if (typeof schema.maximum === "number") {
+      shape = annotate.by(shape, { max: schema.maximum });
+    }
+  }
+
+  if (has(schema, "minLength")) {
+    if (typeof schema.minLength === "number") {
+      shape = annotate.by(shape, { min: schema.minLength });
+    }
+  }
+  if (has(schema, "maxLength")) {
+    if (typeof schema.maxLength === "number") {
+      shape = annotate.by(shape, { max: schema.maxLength });
+    }
+  }
+
+  if (has(schema, "minItems")) {
+    if (typeof schema.minItems === "number") {
+      shape = annotate.by(shape, { min: schema.minItems });
+    }
+  }
+  if (has(schema, "maxItems")) {
+    if (typeof schema.maxItems === "number") {
+      shape = annotate.by(shape, { max: schema.maxItems });
+    }
+  }
+
+  return shape;
+};
+
+export const fromJSONSchemaWithDefs = (
+  schema: unknown,
+): [Record<string, Shape>, Shape] => {
+  if (!isPlainObject(schema)) return [{}, shapes.unknown()];
+
+  const items: Record<string, Shape> = {};
+
+  const definitions =
+    has(schema, "$defs") ? schema.$defs
+    : has(schema, "$definitions") ? schema.$definitions
+    : has(schema, "definitions") ? schema.definitions
+    : has(schema, "defs") ? schema.defs
+    : null;
+
+  if (isPlainObject(definitions)) {
+    for (const [k, v] of Object.entries(definitions)) {
+      const shape = fromJSONSchema(v);
+      if (shape.type === "unknown") continue;
+      if (shape.type === "mapping" && Object.keys(shape.rec).length <= 0)
+        continue;
+
+      items[k] = annotate.named(shape, k);
+    }
+  }
+
+  return [items, fromJSONSchema(schema)];
+};

package/src/phantom.ts

@@ -0,0 +1,3 @@
+export const Phantom = Symbol("Phantom");
+export type Phantom = typeof Phantom;
+export type PhantomIgnore = unknown & any;

package/src/samples/bank.sample.ts

@@ -0,0 +1,25 @@
+import { annotate, shapes } from "../shape";
+
+export const User = annotate.named(
+  shapes.mapping({
+    id: annotate.unique(annotate.primary(shapes.str())),
+    firstname: shapes.str(),
+    lastname: shapes.str(),
+    email: annotate.optional(shapes.str()),
+    embedding: annotate.optional(shapes.vector(300)),
+  }),
+  "User",
+);
+
+export const BankAccount = annotate.named(
+  shapes.mapping({
+    id: annotate.unique(annotate.primary(shapes.str())),
+    userId: annotate.foreign(shapes.str(), "User", "id"),
+    name: shapes.str(),
+    balance: shapes.mapping({
+      value: shapes.float(),
+      currency: shapes.union(shapes.literal("USD"), shapes.literal("EUR")),
+    }),
+  }),
+  "BankAccount",
+);

package/src/shape-utils.ts

@@ -0,0 +1,46 @@
+import { TupleOf } from "./common";
+import { Shape } from "./shape";
+
+export const shapeCompare = (a: Shape, b: Shape): boolean =>
+  JSON.stringify(a) === JSON.stringify(b);
+
+export const simplifyShape = (shape: Shape): Shape => {
+  switch (shape.type) {
+    case "union": {
+      const lookup = new Map<string, number>(
+        shape.ofs.map((s, i) => [JSON.stringify(s), i]),
+      );
+      if (lookup.size === 1)
+        return {
+          ...shape,
+          ofs: [simplifyShape(shape.ofs[0]!)],
+        };
+      return {
+        ...shape,
+        ofs: [...shape.ofs.map((x) => simplifyShape(x))],
+      };
+    }
+    case "array": {
+      return {
+        ...shape,
+        item: simplifyShape(shape.item),
+      };
+    }
+    case "tuple": {
+      return {
+        ...shape,
+        tup: [...shape.tup.map((x) => simplifyShape(x))] as TupleOf<Shape>,
+      };
+    }
+    case "mapping": {
+      return {
+        ...shape,
+        rec: Object.fromEntries(
+          Object.entries(shape.rec).map(([k, v]) => [k, simplifyShape(v)]),
+        ),
+      };
+    }
+    default:
+      return shape;
+  }
+};