@plasius/schema 1.0.17 → 1.1.0

package/tests/field.builder.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { field } from "../src/field";
+import { createSchema } from "../src/schema";
+
+/**
+ * This test verifies that when an older entity (v1.0.0) is validated against a newer
+ * schema (v2.0.0), a field-level `.upgrade()` function is invoked to transform the
+ * value into the new shape, and that validation passes with the upgraded value.
+ */
+
+describe("schema field upgrade flow", () => {
+  it("upgrades old displayName string → new object shape", () => {
+    const userV2 = createSchema(
+      {
+        // v2 requires an object { given, family } instead of a plain string
+        displayName: field
+          .object({
+            given: field.string().required(),
+            family: field.string().required(),
+          })
+          .version("2.0.0")
+          .upgrade((value, { entityFrom, entityTo, fieldTo, fieldName }) => {
+            if (typeof value === "string") {
+              const parts = value.trim().split(/\s+/);
+              const given = parts.shift() ?? "";
+              const family = parts.join(" ") || "Unknown";
+              return { ok: true, value: { given, family } };
+            }
+            return {
+              ok: false,
+              error: `Cannot upgrade ${fieldName} from non-string`,
+            };
+          }),
+      },
+      "User",
+      { version: "2.0.0", table: "users" }
+    );
+
+    const oldEntity = {
+      version: "1.0.0",
+      displayName: "Ada Lovelace",
+    } as const;
+
+    const res = userV2.validate(oldEntity);
+    // Expect our validation contract: no errors and transformed value
+    expect(Array.isArray(res.errors)).toBe(true);
+    expect(res.errors?.length).toBe(0);
+    expect(res.value?.displayName).toEqual({
+      given: "Ada",
+      family: "Lovelace",
+    });
+  });
+
+  it("fails validation when upgrade is not possible", () => {
+    const userV2 = createSchema(
+      {
+        age: field
+          .number()
+          .version("2.0.0")
+          .upgrade((value) => {
+            // Only upgrade from numeric strings like "42"
+            if (typeof value === "string" && /^\d+$/.test(value)) {
+              return { ok: true, value: Number(value) };
+            }
+            return { ok: false, error: "age cannot be upgraded" };
+          })
+          .required(),
+      },
+      "User",
+      { version: "2.0.0", table: "users" }
+    );
+
+    const oldEntity = { version: "1.0.0", age: "forty two" } as const;
+    const res = userV2.validate(oldEntity);
+
+    expect(Array.isArray(res.errors)).toBe(true);
+    expect(res.errors?.length).toBeGreaterThan(0);
+    // Should keep original invalid value when upgrade fails
+    expect(res.value?.age).toBe("forty two");
+  });
+});

package/tests/fields.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// --- Mock FieldBuilder so we can assert how field.ts wires it up ---
+// We mock the *dependency module* that field.ts imports: "./field.builder.js"
+vi.mock("../src/field.builder.js", () => {
+  class MockFieldBuilder<T = unknown> {
+    public type: string;
+    public options?: Record<string, unknown>;
+    public calls: { method: string; args: any[] }[] = [];
+
+    constructor(type: string, options?: Record<string, unknown>) {
+      this.type = type;
+      this.options = options;
+    }
+
+    validator(fn: (value: unknown) => boolean) {
+      this.calls.push({ method: "validator", args: [fn] });
+      return this;
+    }
+
+    PID(cfg: Record<string, unknown>) {
+      this.calls.push({ method: "PID", args: [cfg] });
+      return this;
+    }
+
+    min(n: number) {
+      this.calls.push({ method: "min", args: [n] });
+      return this;
+    }
+
+    max(n: number) {
+      this.calls.push({ method: "max", args: [n] });
+      return this;
+    }
+
+    description(text: string) {
+      this.calls.push({ method: "description", args: [text] });
+      return this;
+    }
+  }
+
+  return { FieldBuilder: MockFieldBuilder };
+});
+
+// Import after the mock so field.ts uses our mocked FieldBuilder
+import { field } from "../src/field";
+
+// Small helper to fetch a recorded call by method name
+const getCall = (fb: any, method: string) =>
+  fb.calls.find((c: any) => c.method === method);
+
+// Helper to run the first validator that was attached and return its boolean result
+const runFirstValidator = (fb: any, value: unknown) => {
+  const call = getCall(fb, "validator");
+  if (!call) throw new Error("No validator attached");
+  const fn = call.args[0] as (v: unknown) => boolean;
+  return fn(value);
+};
+
+// --- Tests ---
+
+describe("field factory basics", () => {
+  it("string/number/boolean create FieldBuilder of correct type", () => {
+    const s = field.string();
+    const n = field.number();
+    const b = field.boolean();
+
+    expect(s.type).toBe("string");
+    expect(n.type).toBe("number");
+    expect(b.type).toBe("boolean");
+  });
+});
+
+describe("validators: email/phone/url/uuid", () => {
+  it("email wires PID, validator, and description and validates", () => {
+    const fb = field.email() as any;
+    expect(fb.type).toBe("string");
+
+    // PID + description were set
+    expect(getCall(fb, "PID").args[0]).toMatchObject({
+      classification: "high",
+      action: "encrypt",
+    });
+    expect(getCall(fb, "description").args[0]).toMatch(/email address/i);
+
+    // Validator behaves sensibly
+    expect(runFirstValidator(fb, "user@example.com")).toBe(true);
+    expect(runFirstValidator(fb, "not-an-email")).toBe(false);
+  });
+
+  it("phone wires PID and validates", () => {
+    const fb = field.phone() as any;
+    expect(getCall(fb, "PID").args[0]).toMatchObject({
+      classification: "high",
+      action: "encrypt",
+    });
+    expect(getCall(fb, "description").args[0]).toMatch(/phone number/i);
+    expect(runFirstValidator(fb, "+442079460018")).toBe(true);
+    expect(runFirstValidator(fb, "123")).toBe(false);
+    expect(runFirstValidator(fb, "123 123 123")).toBe(false);
+    expect(runFirstValidator(fb, "+441234567890123456")).toBe(false);
+  });
+
+  it("url wires PID and validates", () => {
+    const fb = field.url() as any;
+    expect(getCall(fb, "PID").args[0]).toMatchObject({
+      classification: "low",
+      action: "hash",
+    });
+    expect(getCall(fb, "description").args[0]).toMatch(/url/i);
+    expect(runFirstValidator(fb, "https://example.com/path")).toBe(true);
+    expect(runFirstValidator(fb, "ht!tp://bad-url")).toBe(false);
+  });
+
+  it("uuid wires PID and validates", () => {
+    const fb = field.uuid() as any;
+    expect(getCall(fb, "PID").args[0]).toMatchObject({
+      classification: "low",
+      action: "hash",
+    });
+    expect(getCall(fb, "description").args[0]).toMatch(/uuid/i);
+    expect(runFirstValidator(fb, "550e8400-e29b-41d4-a716-446655440000")).toBe(
+      true
+    );
+    expect(runFirstValidator(fb, "not-a-uuid")).toBe(false);
+  });
+});
+
+describe("date/time validators", () => {
+  it("dateTimeISO validates full ISO 8601 date-time", () => {
+    const fb = field.dateTimeISO() as any;
+    expect(getCall(fb, "description").args[0]).toMatch(/ISO 8601/);
+    expect(runFirstValidator(fb, "2023-10-05T14:30:00Z")).toBe(true);
+    expect(runFirstValidator(fb, "2023-13-02T23:04:05Z")).toBe(false);
+    expect(runFirstValidator(fb, "2023-11-02T28:04:05Z")).toBe(false);
+  });
+
+  it("dateISO (date only) validates", () => {
+    const fb = field.dateISO() as any;
+    expect(getCall(fb, "description").args[0]).toMatch(/date only/i);
+    expect(runFirstValidator(fb, "2024-02-29")).toBe(true); // leap day valid
+    expect(runFirstValidator(fb, "2024-02-30")).toBe(false);
+  });
+
+  it("timeISO (time only) validates", () => {
+    const fb = field.timeISO() as any;
+    expect(getCall(fb, "description").args[0]).toMatch(/time only/i);
+    expect(runFirstValidator(fb, "23:59:59")).toBe(true);
+    expect(runFirstValidator(fb, "24:00:00")).toBe(false);
+  });
+});
+
+describe("text validators", () => {
+  it("richText uses validateRichText and marks lower sensitivity", () => {
+    const fb = field.richText() as any;
+    expect(getCall(fb, "PID").args[0]).toMatchObject({
+      classification: "low",
+      action: "clear",
+    });
+    expect(runFirstValidator(fb, "<p>Hello</p>")).toBe(true);
+    expect(runFirstValidator(fb, "<script>alert('x')</script>")).toBe(false);
+  });
+
+  it("generalText uses validateSafeText", () => {
+    const fb = field.generalText() as any;
+    expect(getCall(fb, "PID").args[0]).toMatchObject({
+      classification: "none",
+      action: "none",
+    });
+    expect(runFirstValidator(fb, "Just a sentence.")).toBe(true);
+    expect(runFirstValidator(fb, "<b>Not allowed</b>")).toBe(false);
+  });
+});
+
+describe("geo & versioning", () => {
+  it("latitude enforces -90..90", () => {
+    const fb = field.latitude() as any;
+    expect(getCall(fb, "min").args[0]).toBe(-90);
+    expect(getCall(fb, "max").args[0]).toBe(90);
+    expect(getCall(fb, "description").args[0]).toMatch(/WGS 84/);
+  });
+
+  it("longitude enforces -180..180", () => {
+    const fb = field.longitude() as any;
+    expect(getCall(fb, "min").args[0]).toBe(-180);
+    expect(getCall(fb, "max").args[0]).toBe(180);
+    expect(getCall(fb, "description").args[0]).toMatch(/WGS 84/);
+  });
+
+  it("version uses semver validator", () => {
+    const fb = field.version() as any;
+    expect(getCall(fb, "description").args[0]).toMatch(/semantic version/i);
+    expect(runFirstValidator(fb, "1.2.3")).toBe(true);
+    expect(runFirstValidator(fb, "1.2")).toBe(false);
+  });
+});
+
+describe("codes: country & language", () => {
+  it("countryCode uses ISO 3166 validator", () => {
+    const fb = field.countryCode() as any;
+    expect(getCall(fb, "description").args[0]).toMatch(/ISO 3166/i);
+    expect(runFirstValidator(fb, "GB")).toBe(true);
+    expect(runFirstValidator(fb, "ZZ")).toBe(false);
+  });
+
+  it("languageCode uses BCP 47 validator", () => {
+    const fb = field.languageCode() as any;
+    expect(getCall(fb, "description").args[0]).toMatch(/BCP 47/i);
+    expect(runFirstValidator(fb, "en")).toBe(true);
+    expect(runFirstValidator(fb, "en-GB")).toBe(true);
+    expect(runFirstValidator(fb, "english-UK")).toBe(false);
+  });
+});

package/tests/pii.test.ts

@@ -32,7 +32,7 @@ describe("PII log sanitization", () => {
       }),
     },
     "LogSchema",
-    { version: "1.0", piiEnforcement: "strict" }
+    { version: "1.0.0", piiEnforcement: "strict" }
   );
 
   it("should redact, pseudonymize, pass-through, and omit according to logHandling", () => {
@@ -123,7 +123,7 @@ describe("PII log sanitization", () => {
           }),
         },
         "Alt",
-        { version: "1.0", piiEnforcement: "none" }
+        { version: "1.0.0", piiEnforcement: "none" }
       );
       expect(AltSchema.getPiiAudit()).toEqual([
         {

package/tests/schema.test.ts

@@ -17,7 +17,7 @@ describe("schema.ts – validator coverage", () => {
         bad: undefined as any,
       },
       "BadDef",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
     const r = S.validate({ bad: "anything" });
     expectInvalid(r, "Field definition missing for: bad");
@@ -29,15 +29,15 @@ describe("schema.ts – validator coverage", () => {
       k: field.string().enum(["A", "B", "C"]),
     },
     "StringEnum",
-    { version: "1.0", piiEnforcement: "strict" }
+    { version: "1.0.0", piiEnforcement: "strict" }
   );
 
   const NumberField = createSchema({ n: field.number() }, "NumberField", {
-    version: "1.0",
+    version: "1.0.0",
     piiEnforcement: "strict",
   });
   const BooleanField = createSchema({ b: field.boolean() }, "BooleanField", {
-    version: "1.0",
+    version: "1.0.0",
     piiEnforcement: "strict",
   });
 
@@ -55,23 +55,23 @@ describe("schema.ts – validator coverage", () => {
       }),
     },
     "SimpleObject",
-    { version: "1.0", piiEnforcement: "strict" }
+    { version: "1.0.0", piiEnforcement: "strict" }
   );
 
   const ArrayOfStrings = createSchema(
     { tags: field.array(field.string().enum(["alpha", "beta"])) },
     "ArrayOfStrings",
-    { version: "1.0", piiEnforcement: "strict" }
+    { version: "1.0.0", piiEnforcement: "strict" }
   );
   const ArrayOfNumbers = createSchema(
     { nums: field.array(field.number()) },
     "ArrayOfNumbers",
-    { version: "1.0", piiEnforcement: "strict" }
+    { version: "1.0.0", piiEnforcement: "strict" }
   );
   const ArrayOfBooleans = createSchema(
     { flags: field.array(field.boolean()) },
     "ArrayOfBooleans",
-    { version: "1.0", piiEnforcement: "strict" }
+    { version: "1.0.0", piiEnforcement: "strict" }
   );
 
   const ArrayOfObjects = createSchema(
@@ -85,7 +85,7 @@ describe("schema.ts – validator coverage", () => {
       ),
     },
     "ArrayOfObjects",
-    { version: "1.0", piiEnforcement: "strict" }
+    { version: "1.0.0", piiEnforcement: "strict" }
   );
 
   // 2) Missing required field
@@ -98,7 +98,7 @@ describe("schema.ts – validator coverage", () => {
   it("should fail when immutable field is modified", () => {
     const fixed = field.string().immutable() as any;
     const S = createSchema({ fixed }, "Immutable", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
 
@@ -118,7 +118,7 @@ describe("schema.ts – validator coverage", () => {
     }) as any;
     // required by default (not optional)
     const S = createSchema({ secret }, "PII", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
     const r = S.validate({ secret: "" }); // empty string should trigger strict error
@@ -132,7 +132,7 @@ describe("schema.ts – validator coverage", () => {
         code: field.string().validator((v) => v === "ok"),
       },
       "CustomValidator",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
     const result = S.validate({ code: "nope" });
     expectInvalid(result, "Invalid value for field: code");
@@ -187,7 +187,7 @@ describe("schema.ts – validator coverage", () => {
         }),
       },
       "ChildValidator",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
     const result = S.validate({ o: { a: "x" } });
     expectInvalid(result, "Invalid value for field: o.a");
@@ -218,7 +218,7 @@ describe("schema.ts – validator coverage", () => {
         }),
       },
       "GrandChildValidator",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
     const result = S.validate({ o: { a: "x", nested: { f: true } } });
     expectInvalid(result, "Invalid value for field: o.nested.f");
@@ -293,7 +293,7 @@ describe("schema.ts – validator coverage", () => {
         ),
       },
       "ArrayChildValidator",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
     const result = S.validate({ items: [{ t: "ok" }] });
     expectInvalid(result, "Invalid value for field: items[0].t");
@@ -303,7 +303,7 @@ describe("schema.ts – validator coverage", () => {
   it("should fail when array item is not a valid ref object (or wrong ref type)", () => {
     const refItem = { type: "ref", refType: "asset" } as any;
     const S = createSchema({ items: field.array(refItem) }, "ArrayRefInvalid", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
     // bad id type (number) and missing/incorrect fields should trigger the message
@@ -322,7 +322,7 @@ describe("schema.ts – validator coverage", () => {
       shape: { region: field.string() },
     } as any;
     const S = createSchema({ items: field.array(refItem) }, "ArrayRefMissing", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
     // Valid ref, but missing required shape field 'region'
@@ -340,7 +340,7 @@ describe("schema.ts – validator coverage", () => {
     const S = createSchema(
       { items: field.array(refItem) },
       "ArrayRefChildValidator",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
     const r = S.validate({ items: [{ type: "asset", id: "a1", code: "XYZ" }] });
     expectInvalid(r, "Invalid value for field: items[0].code");
@@ -350,7 +350,7 @@ describe("schema.ts – validator coverage", () => {
   it("should fail when array item type is unsupported", () => {
     const weirdItem = { type: "date" } as any;
     const S = createSchema({ xs: field.array(weirdItem) }, "ArrayUnsupported", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
     const r = S.validate({ xs: ["2025-01-01"] });
@@ -361,7 +361,7 @@ describe("schema.ts – validator coverage", () => {
   it("should fail when ref field is not a valid {type,id} object", () => {
     const refDef = { type: "ref" } as any;
     const S = createSchema({ r: refDef }, "SingleRef", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
     const r = S.validate({ r: { type: "asset", id: 42 } }); // id should be string
@@ -372,7 +372,7 @@ describe("schema.ts – validator coverage", () => {
   it("should fail when field type is unknown", () => {
     const unknownDef = { type: "wat" } as any;
     const S = createSchema({ a: unknownDef }, "UnknownType", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
     const r = S.validate({ a: 123 });
@@ -386,7 +386,7 @@ describe("schema.ts – validator coverage", () => {
         a: field.number(),
       },
       "SchemaLevel",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
 
     // monkey-patch a validator on the schema (if supported by createSchema options)
@@ -399,7 +399,7 @@ describe("schema.ts – validator coverage", () => {
         x: field.string().validator(() => false),
       },
       "SchemaLevel2",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
     const r2 = S2.validate({ x: "anything" });
     expectInvalid(r2, "Invalid value for field: x");
@@ -466,7 +466,7 @@ describe("schema.ts – validator coverage", () => {
   it("should pass when immutable field remains unchanged compared to existing value", () => {
     const fixed = field.string().immutable() as any;
     const S = createSchema({ fixed }, "ImmutableOK", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
     const existing = { fixed: "A" };
@@ -482,7 +482,7 @@ describe("schema.ts – validator coverage", () => {
       purpose: "pii security test",
     }) as any;
     const S = createSchema({ secret }, "PII_OK", {
-      version: "1.0",
+      version: "1.0.0",
       piiEnforcement: "strict",
     });
     const r = S.validate({ secret: "non-empty" });
@@ -493,7 +493,7 @@ describe("schema.ts – validator coverage", () => {
     const S = createSchema(
       { ok: field.string().validator((v) => v === "ok") },
       "CustomValidatorOK",
-      { version: "1.0", piiEnforcement: "strict" }
+      { version: "1.0.0", piiEnforcement: "strict" }
     );
     const r = S.validate({ ok: "ok" });
     expectValid(r);

package/tests/test-utils.ts

@@ -9,7 +9,7 @@ import { SchemaShape, validateUUID } from "../src/index.js";
 // Mock "character" schema
 export const characterSchema = createSchema(
   {
-    name: field.string().description("Character name").version("1.0"),
+    name: field.string().description("Character name").version("1.0.0"),
   },
   "character"
 );
@@ -17,20 +17,20 @@ export type Character = Infer<typeof characterSchema>;
 
 const userShape: SchemaShape = {
   id: field.string().system().validator(validateUUID).immutable(),
-  name: field.string().description("User name").version("1.0"),
+  name: field.string().description("User name").version("1.0.0"),
 
   bestFriend: field
     .string()
     .optional()
     .description("User's best friend ID")
-    .version("1.0")
+    .version("1.0.0")
     .validator(validateUUID),
 
   characters: field
     .array(field.ref("character").as<Character>())
     .optional()
     .description("Characters owned by this user")
-    .version("1.0"),
+    .version("1.0.0"),
 };
 // Mock "user" schema
 export const userSchema = createSchema(userShape, "user");
@@ -49,21 +49,21 @@ export const mockDb: {
 } = {
   "user:user-1": {
     type: "user",
-    version: "1.0",
+    version: "1.0.0",
     name: "Alice",
     bestFriend: { type: "user", id: "user-2" },
     characters: [{ type: "character", id: "char-1" }],
   },
   "user:user-2": {
     type: "user",
-    version: "1.0",
+    version: "1.0.0",
     name: "Bob",
     bestFriend: { type: "user", id: "user-1" }, // cycle!
     characters: [],
   },
   "character:char-1": {
     type: "character",
-    version: "1.0",
+    version: "1.0.0",
     name: "Hero",
   },
 };

package/tests/validate.test.ts

@@ -16,7 +16,7 @@ const userSchema = createSchema(
     characters: field.array(field.ref("character")),
   },
   "user",
-  { version: "1.0", piiEnforcement: "strict" }
+  { version: "1.0.0", piiEnforcement: "strict" }
 );
 
 // Example of a compiled/standalone validator function consumers might use
@@ -27,7 +27,7 @@ describe("validate() with field()-based schema", () => {
   it("validates a correct object", () => {
     const input = {
       type: "user",
-      version: "1.0",
+      version: "1.0.0",
       name: "Alice",
       bestFriend: { type: "user", id: "user-123" },
       characters: [{ type: "character", id: "char-1" }],
@@ -41,7 +41,7 @@ describe("validate() with field()-based schema", () => {
   it("detects missing required field (name)", () => {
     const input = {
       type: "user",
-      version: "1.0",
+      version: "1.0.0",
       bestFriend: { type: "user", id: "user-123" },
       characters: [],
     };
@@ -54,7 +54,7 @@ describe("validate() with field()-based schema", () => {
   it("detects invalid ref shape for bestFriend", () => {
     const input = {
       type: "user",
-      version: "1.0",
+      version: "1.0.0",
       name: "Test",
       bestFriend: { id: "user-123" }, // missing type
       characters: [],
@@ -71,7 +71,7 @@ describe("validate() with field()-based schema", () => {
   it("rejects name that fails custom validator (too short)", () => {
     const input = {
       type: "user",
-      version: "1.0",
+      version: "1.0.0",
       name: "A", // too short per custom validator
       bestFriend: { type: "user", id: "user-123" },
       characters: [],
@@ -87,7 +87,7 @@ describe("validate() with field()-based schema", () => {
   it("accepts name that passes custom validator (>=2 chars)", () => {
     const input = {
       type: "user",
-      version: "1.0",
+      version: "1.0.0",
       name: "Al",
       bestFriend: { type: "user", id: "user-123" },
       characters: [],