shapedef 1.0.0

package/src/translations/translation.ts

@@ -0,0 +1,3 @@
+import { Shape } from "../shape";
+
+export type TranslationFunc<T extends any = any> = (shape: Shape) => T;

package/src/translations/typescript.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect } from "vitest";
+import { annotate, shapes } from "../shape";
+import { typescript } from "./typescript";
+
+describe("typescript", (it) => {
+  it("translates primitive types", () => {
+    expect(typescript(shapes.int())).toBe("number");
+    expect(typescript(shapes.float())).toBe("number");
+    expect(typescript(shapes.number())).toBe("number");
+    expect(typescript(shapes.bool())).toBe("boolean");
+    expect(typescript(shapes.str())).toBe("string");
+    expect(typescript(shapes.date())).toBe("Date");
+    expect(typescript(shapes.nil())).toBe("null");
+    expect(typescript(shapes.unknown())).toBe("unknown");
+  });
+
+  it("translates unions", () => {
+    expect(typescript(shapes.union(shapes.int(), shapes.bool()))).toBe(
+      "number | boolean",
+    );
+  });
+
+  it("translates arrays", () => {
+    expect(typescript(shapes.array(shapes.number()))).toBe("Array<number>");
+  });
+
+  it("translates tuples", () => {
+    expect(typescript(shapes.tuple(shapes.number(), shapes.number()))).toBe(
+      "[number, number]",
+    );
+  });
+
+  it("translates anonymous mappings", () => {
+    expect(
+      typescript(
+        shapes.mapping({
+          name: shapes.str(),
+          age: annotate.optional(shapes.number()),
+        }),
+      ),
+    ).toBe(["{", "  name: string,", "  age?: number", "}"].join("\n"));
+  });
+
+  it("translates named mappings", () => {
+    expect(
+      typescript(
+        annotate.named(
+          shapes.mapping({
+            name: shapes.str(),
+            age: annotate.optional(shapes.number()),
+          }),
+          "Foo",
+        ),
+      ),
+    ).toBe(
+      ["export interface Foo {", "  name: string,", "  age?: number", "}"].join(
+        "\n",
+      ),
+    );
+  });
+});

package/src/translations/typescript.ts

@@ -0,0 +1,142 @@
+import { mkpad } from "../common/padding";
+import { Shape } from "../shape";
+import { TranslationFunc } from "./translation";
+
+type Context = {
+  padding: number;
+  depth: number;
+};
+
+const incDepth = (ctx: Context): Context => ({ ...ctx, depth: ctx.depth + 1 });
+
+const maybeTypeAlias = (shape: Shape, ctx: Context, out: string): string => {
+  if (ctx.depth > 0) return out;
+  const name = shape.anno.name || shape.anno.title;
+  if (name && !name.includes(" ")) return `export type ${name} = ${out}`;
+  return out;
+};
+
+const toBatched = <T>(arr: T[], batchSize: number): Array<T[]> => {
+  const batches: Array<T[]> = [];
+
+  for (let i = 0; i < arr.length; i += batchSize) {
+    batches.push(arr.slice(i, i + batchSize));
+  }
+
+  return batches;
+};
+
+const createComments = (shape: Shape): string[] => {
+  const parts: string[] = [];
+  const description = (shape.anno.description || "").trim();
+  if (description.length > 0) {
+    const chars = Array.from(description.trim());
+    const batches = toBatched(chars, 80);
+    const lines = batches.map((x) => x.join(""));
+    parts.push(...lines);
+  }
+  if (typeof shape.anno.min === "number") {
+    parts.push(`min: ${shape.anno.min}`);
+  }
+  if (typeof shape.anno.max === "number") {
+    parts.push(`max: ${shape.anno.max}`);
+  }
+  return parts;
+};
+
+const ts = (shape: Shape, ctx: Context): string => {
+  switch (shape.type) {
+    case "vector":
+      return "number[]";
+    case "number":
+      return "number";
+    case "int":
+      return "number";
+    case "float":
+      return "number";
+    case "str":
+      return "string";
+    case "bool":
+      return "boolean";
+    case "date":
+      return "Date";
+    case "nil":
+      return "null";
+    case "unknown":
+      return "unknown";
+    case "literal-number":
+      return `${shape.value}`;
+    case "literal-int":
+      return `${shape.value}`;
+    case "literal-float":
+      return `${shape.value}`;
+    case "literal-str":
+      return `'${shape.value}'`;
+    case "literal-bool":
+      return `${shape.value}`;
+    case "ref":
+      return shape.name
+        .replaceAll("#/definitions/", "")
+        .replaceAll("#/$defs/", "")
+        .replaceAll("-", "_");
+    case "array":
+      return maybeTypeAlias(
+        shape,
+        ctx,
+        `Array<${ts(shape.item, incDepth(ctx))}>`,
+      );
+    case "tuple":
+      return `[${shape.tup.map((x) => ts(x, incDepth(ctx))).join(", ")}]`;
+    case "union":
+      return maybeTypeAlias(
+        shape,
+        ctx,
+        Array.from(new Set(shape.ofs.map((x) => ts(x, incDepth(ctx))))).join(
+          " | ",
+        ),
+      );
+    case "mapping": {
+      const parts: string[] = [];
+      const members: string[] = [];
+      const name = shape.anno.name;
+      if (name) {
+        const replaced = name.replaceAll("-", "_");
+        parts.push(`export interface ${replaced} `);
+      }
+      parts.push("{");
+      parts.push("\n");
+      for (const [k, v] of Object.entries(shape.rec)) {
+        const member: string[] = [];
+
+        const comments = createComments(v);
+        if (comments.length > 0) {
+          member.push(mkpad(ctx.padding + 2) + "/**");
+          member.push("\n");
+          member.push(
+            comments
+              .map((cmt) => `${mkpad(ctx.padding + 2)}* ${cmt}`)
+              .join("\n"),
+          );
+          member.push("\n");
+          member.push(mkpad(ctx.padding + 2) + "**/");
+          member.push("\n");
+        }
+        member.push(mkpad(ctx.padding + 2));
+        member.push(k);
+        if (v.anno.optional) member.push("?");
+        member.push(": ");
+        member.push(ts(v, incDepth({ ...ctx, padding: ctx.padding + 2 })));
+        members.push(member.join(""));
+      }
+      parts.push(members.join(",\n"));
+      parts.push("\n");
+      parts.push(mkpad(ctx.padding));
+      parts.push("}");
+      return parts.join("");
+    }
+  }
+};
+
+export const typescript: TranslationFunc<string> = (shape) => {
+  return ts(shape, { padding: 0, depth: 0 });
+};

package/src/validation.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect } from "vitest";
+import { annotate, shapes } from "./shape";
+import { validate } from "./validation";
+
+describe("validate", (it) => {
+  it("validates str", () => {
+    expect(validate("hello", shapes.str())).toEqual({ ok: true });
+    expect(validate(42, shapes.str())).toMatchObject({ ok: false });
+  });
+
+  it("validates bool", () => {
+    expect(validate(true, shapes.bool())).toEqual({ ok: true });
+    expect(validate(false, shapes.bool())).toEqual({ ok: true });
+    expect(validate("true", shapes.bool())).toMatchObject({ ok: false });
+  });
+
+  it("validates int", () => {
+    expect(validate(1, shapes.int())).toEqual({ ok: true });
+    expect(validate(1.5, shapes.int())).toMatchObject({ ok: false });
+    expect(validate("1", shapes.int())).toMatchObject({ ok: false });
+  });
+
+  it("validates float", () => {
+    expect(validate(1.5, shapes.float())).toEqual({ ok: true });
+    expect(validate(1, shapes.float())).toMatchObject({ ok: false });
+  });
+
+  it("validates number", () => {
+    expect(validate(1, shapes.number())).toEqual({ ok: true });
+    expect(validate(1.5, shapes.number())).toEqual({ ok: true });
+    expect(validate("1", shapes.number())).toMatchObject({ ok: false });
+  });
+
+  it("validates nil", () => {
+    expect(validate(null, shapes.nil())).toEqual({ ok: true });
+    expect(validate(undefined, shapes.nil())).toMatchObject({ ok: false });
+    expect(validate(0, shapes.nil())).toMatchObject({ ok: false });
+  });
+
+  it("validates date", () => {
+    expect(validate(new Date(), shapes.date())).toEqual({ ok: true });
+    expect(validate("2024-01-01", shapes.date())).toMatchObject({ ok: false });
+  });
+
+  it("validates unknown (always ok)", () => {
+    expect(validate(null, shapes.unknown())).toEqual({ ok: true });
+    expect(validate(42, shapes.unknown())).toEqual({ ok: true });
+    expect(validate("anything", shapes.unknown())).toEqual({ ok: true });
+  });
+
+  it("validates literals", () => {
+    expect(validate("hello", shapes.literalStr("hello"))).toEqual({ ok: true });
+    expect(validate("world", shapes.literalStr("hello"))).toMatchObject({
+      ok: false,
+    });
+
+    expect(validate(true, shapes.literalBool(true))).toEqual({ ok: true });
+    expect(validate(false, shapes.literalBool(true))).toMatchObject({
+      ok: false,
+    });
+
+    expect(validate(1, shapes.literalInt(1))).toEqual({ ok: true });
+    expect(validate(2, shapes.literalInt(1))).toMatchObject({ ok: false });
+
+    expect(validate(1.5, shapes.literalFloat(1.5))).toEqual({ ok: true });
+    expect(validate(1.6, shapes.literalFloat(1.5))).toMatchObject({
+      ok: false,
+    });
+
+    expect(validate(42, shapes.literalNumber(42))).toEqual({ ok: true });
+    expect(validate(43, shapes.literalNumber(42))).toMatchObject({ ok: false });
+  });
+
+  it("validates array", () => {
+    expect(validate([1, 2, 3], shapes.array(shapes.int()))).toEqual({
+      ok: true,
+    });
+    expect(validate([], shapes.array(shapes.str()))).toEqual({ ok: true });
+    expect(validate("not an array", shapes.array(shapes.str()))).toMatchObject({
+      ok: false,
+    });
+    expect(validate([1, "oops", 3], shapes.array(shapes.int()))).toMatchObject({
+      ok: false,
+      path: [1],
+    });
+  });
+
+  it("validates tuple", () => {
+    expect(
+      validate([1, "hello"], shapes.tuple(shapes.int(), shapes.str())),
+    ).toEqual({ ok: true });
+
+    expect(
+      validate([1], shapes.tuple(shapes.int(), shapes.str())),
+    ).toMatchObject({ ok: false });
+
+    expect(
+      validate([1, 2], shapes.tuple(shapes.int(), shapes.str())),
+    ).toMatchObject({ ok: false, path: [1] });
+
+    expect(validate("not a tuple", shapes.tuple(shapes.int()))).toMatchObject({
+      ok: false,
+    });
+  });
+
+  it("validates vector", () => {
+    expect(validate([1, 2, 3], shapes.vector(3))).toEqual({ ok: true });
+    expect(validate([1, 2], shapes.vector(3))).toMatchObject({ ok: false });
+    expect(validate([1, "x", 3], shapes.vector(3))).toMatchObject({
+      ok: false,
+    });
+    expect(validate("not an array", shapes.vector(3))).toMatchObject({
+      ok: false,
+    });
+  });
+
+  it("validates mapping", () => {
+    expect(
+      validate(
+        { name: "Alice", age: 30 },
+        shapes.mapping({ name: shapes.str(), age: shapes.int() }),
+      ),
+    ).toEqual({ ok: true });
+
+    expect(
+      validate(
+        { name: "Alice" },
+        shapes.mapping({ name: shapes.str(), age: shapes.int() }),
+      ),
+    ).toMatchObject({ ok: false, path: ["age"] });
+
+    expect(
+      validate(
+        { name: 99, age: 30 },
+        shapes.mapping({ name: shapes.str(), age: shapes.int() }),
+      ),
+    ).toMatchObject({ ok: false, path: ["name"] });
+
+    expect(
+      validate("not an object", shapes.mapping({ name: shapes.str() })),
+    ).toMatchObject({ ok: false });
+  });
+
+  it("validates mapping with optional fields", () => {
+    const shape = shapes.mapping({
+      name: shapes.str(),
+      nickname: annotate.optional(shapes.str()),
+    });
+
+    expect(validate({ name: "Alice" }, shape)).toEqual({ ok: true });
+    expect(validate({ name: "Alice", nickname: "Al" }, shape)).toEqual({
+      ok: true,
+    });
+    expect(validate({ nickname: "Al" }, shape)).toMatchObject({ ok: false });
+  });
+
+  it("validates union", () => {
+    const shape = shapes.union(shapes.str(), shapes.int());
+    expect(validate("hello", shape)).toEqual({ ok: true });
+    expect(validate(42, shape)).toEqual({ ok: true });
+    expect(validate(true, shape)).toMatchObject({ ok: false });
+  });
+
+  it("returns error path for nested failures", () => {
+    const shape = shapes.mapping({
+      user: shapes.mapping({
+        age: shapes.int(),
+      }),
+    });
+    const result = validate({ user: { age: "not a number" } }, shape);
+    expect(result).toMatchObject({ ok: false, path: ["user", "age"] });
+  });
+
+  it("returns error for ref shapes", () => {
+    expect(validate("anything", shapes.ref("MyType"))).toMatchObject({
+      ok: false,
+    });
+  });
+});

package/src/validation.ts

@@ -0,0 +1,135 @@
+import { has, isPlainObject } from "./common";
+import { Shape } from "./shape";
+
+export type ValidationResult =
+  | {
+      ok: true;
+    }
+  | {
+      ok: false;
+      error: string;
+      path: PropertyKey[];
+    };
+
+const ok = (): Extract<ValidationResult, { ok: true }> => ({ ok: true });
+const err = (
+  error: string,
+  path: PropertyKey[],
+): Extract<ValidationResult, { ok: false }> => ({
+  ok: false,
+  error,
+  path,
+});
+
+const maybe = (
+  result: boolean,
+  error: string,
+  path: PropertyKey[],
+): ValidationResult => (result ? ok() : err(error, path));
+
+export function validate(x: unknown, shape: Shape): ValidationResult {
+  function check(
+    x: unknown,
+    shape: Shape,
+    path: PropertyKey[],
+  ): ValidationResult {
+    switch (shape.type) {
+      case "literal-bool":
+      case "literal-str":
+      case "literal-int":
+      case "literal-float":
+      case "literal-number":
+        return maybe(
+          x === shape.value,
+          `expected literal ${shape.value}`,
+          path,
+        );
+      case "str":
+        return maybe(typeof x === "string", "expected a string", path);
+      case "bool":
+        return maybe(typeof x === "boolean", "expected a boolean", path);
+      case "int":
+        return maybe(
+          typeof x === "number" && Number.isInteger(x),
+          "expected an integer",
+          path,
+        );
+      case "float":
+        return maybe(
+          typeof x === "number" && !Number.isInteger(x),
+          "expected a float",
+          path,
+        );
+      case "number":
+        return maybe(typeof x === "number", "expected a number", path);
+      case "nil":
+        return maybe(x === null, "expected null", path);
+      case "date":
+        return maybe(x instanceof Date, "expected a date", path);
+      case "unknown":
+        return ok();
+      case "array": {
+        if (!Array.isArray(x)) return err("expected an array", path);
+        for (let i = 0; i < x.length; i++) {
+          const item = x[i];
+          const result = check(item, shape.item, [...path, i]);
+          if (!result.ok) return result;
+        }
+        return ok();
+      }
+      case "mapping": {
+        if (!isPlainObject(x)) return err("expected a plain object", path);
+        for (const [k, v] of Object.entries(shape.rec)) {
+          if (!has(x, k) || typeof x[k] === "undefined") {
+            if (v.anno.optional || v.type === "unknown") continue;
+            return err(`expected property ${k} to exist`, [...path, k]);
+          }
+          const result = check(x[k], v, [...path, k]);
+          if (!result.ok) return result;
+        }
+        return ok();
+      }
+      case "ref":
+        return err(`cannot validate ref`, path);
+      case "tuple": {
+        if (!Array.isArray(x)) return err("expected a tuple / array", path);
+        if (x.length !== shape.tup.length)
+          return err(
+            `expected a tuple of length ${shape.tup.length} but got a tuple / array of length ${x.length}`,
+            path,
+          );
+        for (let i = 0; i < shape.tup.length; i++) {
+          const v = shape.tup[i]!;
+          const result = check(x[i], v, [...path, i]);
+          if (!result.ok) return result;
+        }
+        return ok();
+      }
+      case "vector": {
+        if (!Array.isArray(x)) return err(`expected an array (vector)`, path);
+        if (x.length !== shape.dims)
+          return err(
+            `expected a vector with dimension ${shape.dims} but got dimensions ${x.length}`,
+            path,
+          );
+        if (!x.every((v) => typeof v === "number"))
+          return err(
+            `expected a numeric vector but it contained other types`,
+            path,
+          );
+        return ok();
+      }
+      case "union": {
+        let lastResult: ValidationResult = ok();
+        for (const v of shape.ofs) {
+          const result = check(x, v, path);
+          if (result.ok) return ok();
+          lastResult = result;
+        }
+        return lastResult;
+      }
+    }
+  }
+
+  return check(x, shape, []);
+}

package/tsconfig.cjs.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/cjs",
+    "module": "commonjs",
+    "moduleResolution": "node10"
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.test.ts", "./src/**/*.sample.ts"]
+}

package/tsconfig.esm.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "module": "nodenext",
+    "target": "esnext"
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.test.ts", "./src/**/*.sample.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "module": "nodenext",
+    "target": "esnext",
+    "lib": ["esnext"],
+    "types": ["node"],
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "strict": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}