shapedef 1.0.21 → 1.0.23

package/src/shape.coerce.test.ts

@@ -0,0 +1,285 @@
+import { describe, expect } from "vitest";
+import { annotate, shapes } from "./shape";
+
+describe("annotate.coerce", (it) => {
+  // ── primitives ──────────────────────────────────────────────────────────
+
+  it("coerces str: passthrough for strings", () => {
+    expect(annotate.coerce("hello", shapes.str())).toBe("hello");
+  });
+
+  it("coerces str: converts number to string", () => {
+    expect(annotate.coerce(42, shapes.str())).toBe("42");
+  });
+
+  it("coerces str: converts boolean to string", () => {
+    expect(annotate.coerce(true, shapes.str())).toBe("true");
+  });
+
+  it("coerces str: converts null to string", () => {
+    expect(annotate.coerce(null, shapes.str())).toBe("null");
+  });
+
+  it("coerces number: passthrough for numbers", () => {
+    expect(annotate.coerce(3.14, shapes.number())).toBe(3.14);
+    expect(annotate.coerce(0, shapes.number())).toBe(0);
+  });
+
+  it("coerces number: converts numeric string", () => {
+    expect(annotate.coerce("3.14", shapes.number())).toBe(3.14);
+    expect(annotate.coerce("", shapes.number())).toBe(0);
+  });
+
+  it("coerces number: returns 0 for non-numeric input", () => {
+    expect(annotate.coerce(null, shapes.number())).toBe(0);
+    expect(annotate.coerce(false, shapes.number())).toBe(0);
+  });
+
+  it("coerces float: same rules as number", () => {
+    expect(annotate.coerce(1.5, shapes.float())).toBe(1.5);
+    expect(annotate.coerce("2.5", shapes.float())).toBe(2.5);
+    expect(annotate.coerce(null, shapes.float())).toBe(0);
+  });
+
+  it("coerces int: truncates floats", () => {
+    expect(annotate.coerce(3.9, shapes.int())).toBe(3);
+    expect(annotate.coerce(-3.9, shapes.int())).toBe(-3);
+  });
+
+  it("coerces int: converts numeric string", () => {
+    expect(annotate.coerce("7.8", shapes.int())).toBe(7);
+    expect(annotate.coerce("", shapes.int())).toBe(0);
+  });
+
+  it("coerces int: returns 0 for non-numeric input", () => {
+    expect(annotate.coerce(null, shapes.int())).toBe(0);
+  });
+
+  it("coerces bool: passthrough for booleans", () => {
+    expect(annotate.coerce(true, shapes.bool())).toBe(true);
+    expect(annotate.coerce(false, shapes.bool())).toBe(false);
+  });
+
+  it("coerces bool: truthy string values", () => {
+    expect(annotate.coerce("true", shapes.bool())).toBe(true);
+    expect(annotate.coerce("1", shapes.bool())).toBe(true);
+    expect(annotate.coerce("yes", shapes.bool())).toBe(true);
+    expect(annotate.coerce("TRUE", shapes.bool())).toBe(true);
+  });
+
+  it("coerces bool: falsy string values", () => {
+    expect(annotate.coerce("false", shapes.bool())).toBe(false);
+    expect(annotate.coerce("no", shapes.bool())).toBe(false);
+    expect(annotate.coerce("0", shapes.bool())).toBe(false);
+    expect(annotate.coerce("", shapes.bool())).toBe(false);
+  });
+
+  it("coerces bool: truthy/falsy non-string values", () => {
+    expect(annotate.coerce(1, shapes.bool())).toBe(true);
+    expect(annotate.coerce(0, shapes.bool())).toBe(false);
+    expect(annotate.coerce(null, shapes.bool())).toBe(false);
+  });
+
+  it("coerces nil: always returns null", () => {
+    expect(annotate.coerce("anything", shapes.nil())).toBeNull();
+    expect(annotate.coerce(42, shapes.nil())).toBeNull();
+    expect(annotate.coerce(null, shapes.nil())).toBeNull();
+  });
+
+  it("coerces unknown: returns value as-is", () => {
+    const obj = { x: 1 };
+    expect(annotate.coerce(obj, shapes.unknown())).toBe(obj);
+    expect(annotate.coerce(null, shapes.unknown())).toBeNull();
+    expect(annotate.coerce(42, shapes.unknown())).toBe(42);
+  });
+
+  it("coerces date: passthrough for Date instances", () => {
+    const d = new Date("2024-01-01");
+    expect(annotate.coerce(d, shapes.date())).toBe(d);
+  });
+
+  it("coerces date: parses ISO string", () => {
+    const result = annotate.coerce("2024-06-15", shapes.date());
+    expect(result).toBeInstanceOf(Date);
+    expect((result as Date).getFullYear()).toBe(2024);
+  });
+
+  it("coerces date: parses numeric timestamp", () => {
+    const ts = 1700000000000;
+    const result = annotate.coerce(ts, shapes.date());
+    expect(result).toBeInstanceOf(Date);
+    expect((result as Date).getTime()).toBe(ts);
+  });
+
+  it("coerces date: returns a Date for unknown input", () => {
+    expect(annotate.coerce(null, shapes.date())).toBeInstanceOf(Date);
+  });
+
+  // ── literals ─────────────────────────────────────────────────────────────
+
+  it("coerces literalStr: always returns the literal value", () => {
+    expect(annotate.coerce("anything", shapes.literalStr("hello"))).toBe(
+      "hello",
+    );
+    expect(annotate.coerce(42, shapes.literalStr("hello"))).toBe("hello");
+  });
+
+  it("coerces literalBool: always returns the literal value", () => {
+    expect(annotate.coerce("false", shapes.literalBool(true))).toBe(true);
+    expect(annotate.coerce(99, shapes.literalBool(false))).toBe(false);
+  });
+
+  it("coerces literalInt / literalFloat / literalNumber: always returns the literal value", () => {
+    expect(annotate.coerce("anything", shapes.literalInt(5))).toBe(5);
+    expect(annotate.coerce("anything", shapes.literalFloat(1.5))).toBe(1.5);
+    expect(annotate.coerce("anything", shapes.literalNumber(42))).toBe(42);
+  });
+
+  // ── bytes ────────────────────────────────────────────────────────────────
+
+  it("coerces bytes: passthrough for Uint8Array", () => {
+    const buf = new Uint8Array([1, 2, 3]);
+    expect(annotate.coerce(buf, shapes.bytes())).toBe(buf);
+  });
+
+  it("coerces bytes: converts number array", () => {
+    expect(annotate.coerce([10, 20, 30], shapes.bytes())).toEqual(
+      new Uint8Array([10, 20, 30]),
+    );
+  });
+
+  it("coerces bytes: parses comma-separated string", () => {
+    expect(annotate.coerce("1,2,3", shapes.bytes())).toEqual(
+      new Uint8Array([1, 2, 3]),
+    );
+  });
+
+  it("coerces bytes: returns empty Uint8Array for unknown input", () => {
+    expect(annotate.coerce(null, shapes.bytes())).toEqual(new Uint8Array());
+  });
+
+  // ── array ────────────────────────────────────────────────────────────────
+
+  it("coerces array: passthrough for arrays", () => {
+    expect(annotate.coerce([1, 2, 3], shapes.array(shapes.int()))).toEqual([
+      1, 2, 3,
+    ]);
+  });
+
+  it("coerces array: converts each item", () => {
+    expect(
+      annotate.coerce(["1", "2", "3"], shapes.array(shapes.int())),
+    ).toEqual([1, 2, 3]);
+  });
+
+  it("coerces array: parses comma-separated string", () => {
+    expect(annotate.coerce("10, 20, 30", shapes.array(shapes.int()))).toEqual([
+      10, 20, 30,
+    ]);
+  });
+
+  it("coerces array: returns empty array for other types", () => {
+    expect(annotate.coerce(null, shapes.array(shapes.str()))).toEqual([]);
+  });
+
+  // ── tuple ────────────────────────────────────────────────────────────────
+
+  it("coerces tuple: converts array elements per shape", () => {
+    expect(
+      annotate.coerce(["42", true], shapes.tuple(shapes.int(), shapes.bool())),
+    ).toEqual([42, true]);
+  });
+
+  it("coerces tuple: parses comma-separated string", () => {
+    expect(
+      annotate.coerce("hello,1", shapes.tuple(shapes.str(), shapes.int())),
+    ).toEqual(["hello", 1]);
+  });
+
+  it("coerces tuple: fills missing elements with coerced nulls", () => {
+    const result = annotate.coerce(
+      null,
+      shapes.tuple(shapes.int(), shapes.str()),
+    );
+    expect(result).toEqual([0, "null"]);
+  });
+
+  // ── vector ───────────────────────────────────────────────────────────────
+
+  it("coerces vector: passthrough for number array", () => {
+    expect(annotate.coerce([1, 2, 3], shapes.vector(3))).toEqual([1, 2, 3]);
+  });
+
+  it("coerces vector: parses comma-separated string", () => {
+    expect(annotate.coerce("1.0, 2.0, 3.0", shapes.vector(3))).toEqual([
+      1, 2, 3,
+    ]);
+  });
+
+  it("coerces vector: returns empty array for unknown input", () => {
+    expect(annotate.coerce(null, shapes.vector(3))).toEqual([]);
+  });
+
+  // ── mapping ──────────────────────────────────────────────────────────────
+
+  it("coerces mapping: passthrough for plain objects", () => {
+    expect(
+      annotate.coerce(
+        { name: "Alice", age: 30 },
+        shapes.mapping({ name: shapes.str(), age: shapes.int() }),
+      ),
+    ).toEqual({ name: "Alice", age: 30 });
+  });
+
+  it("coerces mapping: coerces each field's type", () => {
+    expect(
+      annotate.coerce(
+        { name: 42, age: "30" },
+        shapes.mapping({ name: shapes.str(), age: shapes.int() }),
+      ),
+    ).toEqual({ name: "42", age: 30 });
+  });
+
+  it("coerces mapping: parses JSON string", () => {
+    expect(
+      annotate.coerce(
+        '{"x": "1", "y": "2"}',
+        shapes.mapping({ x: shapes.int(), y: shapes.int() }),
+      ),
+    ).toEqual({ x: 1, y: 2 });
+  });
+
+  it("coerces mapping: fills missing fields with defaults", () => {
+    expect(
+      annotate.coerce(
+        {},
+        shapes.mapping({ count: shapes.int(), label: shapes.str() }),
+      ),
+    ).toEqual({ count: 0, label: "undefined" });
+  });
+
+  it("coerces mapping: returns coerced defaults for non-object input", () => {
+    expect(
+      annotate.coerce(null, shapes.mapping({ active: shapes.bool() })),
+    ).toEqual({ active: false });
+  });
+
+  // ── ref ───────────────────────────────────────────────────────────────────
+
+  it("coerces ref: returns value as-is", () => {
+    const val = { id: 1 };
+    expect(annotate.coerce(val, shapes.ref("MyType"))).toBe(val);
+    expect(annotate.coerce("anything", shapes.ref("MyType"))).toBe("anything");
+  });
+
+  // ── union ─────────────────────────────────────────────────────────────────
+
+  it("coerces union: uses first member's shape", () => {
+    const shape = shapes.union(shapes.int(), shapes.str());
+    expect(annotate.coerce("42", shape)).toBe(42);
+  });
+
+  it("coerces union: handles single-member union", () => {
+    expect(annotate.coerce("hello", shapes.union(shapes.str()))).toBe("hello");
+  });
+});

package/src/shape.ts

@@ -107,6 +107,7 @@ 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 ShapeBytes extends ShapeWithOutput<"bytes", Uint8Array> {}
 
 export interface ShapeLiteralFloat<
   Value extends number = number,
@@ -197,6 +198,7 @@ export type Shape =
   | ShapeDate
   | ShapeNil
   | ShapeUnknown
+  | ShapeBytes
   | ShapeLiteralFloat
   | ShapeLiteralInt
   | ShapeLiteralNumber
@@ -288,6 +290,14 @@ export namespace shapes {
     };
   }
 
+  export function bytes(): ShapeBytes {
+    return {
+      type: "bytes",
+      anno: {},
+      ...createPhantom(),
+    };
+  }
+
   export function literalFloat<Value extends number>(
     value: Value,
   ): ShapeLiteralFloat<Value> {
@@ -539,4 +549,117 @@ export namespace annotate {
     }
     return shapes.unknown();
   }
+
+  export function coerce<S extends Shape>(
+    x: unknown,
+    shape: S,
+  ): OutputOfShape<S> {
+    const convert = (x: unknown, shape: Shape): unknown => {
+      switch (shape.type) {
+        case "str":
+          if (typeof x === "string") return x;
+          return `${x}`;
+        case "literal-str":
+        case "literal-int":
+        case "literal-float":
+        case "literal-number":
+        case "literal-bool":
+          return shape.value;
+        case "number":
+        case "float":
+          if (typeof x === "number") return x;
+          if (typeof x === "string") return Number(x || 0);
+          return 0;
+        case "int":
+          if (typeof x === "number") return Math.trunc(x);
+          if (typeof x === "string") return Math.trunc(Number(x || 0));
+          return 0;
+        case "nil":
+          return null;
+        case "bool":
+          if (typeof x === "boolean") return x;
+          if (typeof x === "string")
+            return ["true", "1", "yes"].includes(x.trim().toLowerCase());
+          return !!x;
+        case "date":
+          if (x instanceof Date) return x;
+          if (typeof x === "string" || typeof x === "number")
+            return new Date(x);
+          return new Date();
+        case "unknown":
+          return x;
+        case "vector":
+          if (Array.isArray(x)) return x.map((v) => convert(v, shapes.float()));
+          if (typeof x === "string")
+            return x
+              .replaceAll(/\[|\{|\}|\]/g, "")
+              .split(",")
+              .map((v) => v.trim())
+              .map((v) => convert(v, shapes.float()));
+          return [];
+        case "array":
+          if (Array.isArray(x)) return x.map((v) => convert(v, shape.item));
+          if (typeof x === "string")
+            return x
+              .replaceAll(/\[|\{|\}|\]/g, "")
+              .split(",")
+              .map((v) => v.trim())
+              .map((v) => convert(v, shape.item));
+          return [];
+        case "tuple":
+          if (Array.isArray(x))
+            return shape.tup.map((s, i) => convert(x[i], s));
+          if (typeof x === "string") {
+            const parts = x
+              .replaceAll(/\[|\{|\}|\]/g, "")
+              .split(",")
+              .map((v) => v.trim());
+            return shape.tup.map((s, i) => convert(parts[i], s));
+          }
+          return shape.tup.map((s) => convert(null, s));
+        case "bytes":
+          if (x instanceof Uint8Array) return x;
+          if (Array.isArray(x))
+            return new Uint8Array(
+              x.map((v) => convert(v, shapes.int())) as number[],
+            );
+          if (typeof x === "string")
+            return new Uint8Array(
+              x
+                .replaceAll(/\[|\{|\}|\]/g, "")
+                .split(",")
+                .map((v) => v.trim())
+                .map((v) => convert(v, shapes.number())) as number[],
+            );
+          return new Uint8Array();
+        case "ref":
+          return x;
+        case "union":
+          const t = shape.ofs[0];
+          return convert(x, t || shapes.unknown());
+        case "mapping":
+          let obj: Record<string, unknown> = {};
+          if (isPlainObject(x)) {
+            obj = x;
+          } else if (typeof x === "string") {
+            const trimmed = x.trim();
+            if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+              try {
+                obj = JSON.parse(x) as Record<string, unknown>;
+              } catch {}
+            }
+          }
+          return Object.assign(
+            {},
+            ...Object.entries(shape.rec).map(([k, t]) => {
+              return {
+                [k]: convert(obj[k], t),
+              };
+            }),
+          );
+      }
+    };
+
+    return convert(x, shape) as OutputOfShape<S>;
+  }
 }

package/src/translations/postgres.ts

@@ -51,6 +51,8 @@ const pgType = (shape: Shape): string => {
       return `vector(${shape.dims})`;
     case "mapping":
       return "JSONB";
+    case "bytes":
+      return "BYTEA";
   }
 };
 

package/src/translations/typescript.test.ts

@@ -12,6 +12,7 @@ describe("typescript", (it) => {
     expect(typescript(shapes.date())).toBe("Date");
     expect(typescript(shapes.nil())).toBe("null");
     expect(typescript(shapes.unknown())).toBe("unknown");
+    expect(typescript(shapes.bytes())).toBe("Uint8Array");
   });
 
   it("translates unions", () => {

package/src/translations/typescript.ts

@@ -136,6 +136,8 @@ const ts = (shape: Shape, ctx: Context): string => {
       return "null";
     case "unknown":
       return "unknown";
+    case "bytes":
+      return "Uint8Array";
     case "literal-number":
       return `${shape.value}`;
     case "literal-int":

package/src/validation.ts

@@ -94,6 +94,8 @@ export function validate(x: unknown, shape: Shape): ValidationResult {
         return maybe(x instanceof Date, "expected a date", path);
       case "unknown":
         return ok();
+      case "bytes":
+        return maybe(x instanceof Uint8Array, "expected a Uint8Array", path);
       case "array": {
         if (!Array.isArray(x)) return err("expected an array", path);
         if (shape.anno.min !== undefined && x.length < shape.anno.min)