@plasius/schema 1.0.18 → 1.1.0

package/.github/workflows/cd.yml

@@ -2,6 +2,21 @@ name: CD (Publish to npm)
 
 on:
   workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        type: choice
+        default: patch
+        options:
+          - patch
+          - minor
+          - major
+          - none
+      preid:
+        description: "Pre-release id (e.g. beta, rc). Leave blank for stable"
+        required: false
+        type: string
 
 permissions:
   contents: write
@@ -26,11 +41,46 @@ jobs:
         id: pkg
         env:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          BUMP: ${{ inputs.bump }}
+          PREID: ${{ inputs.preid }}
         run: |
           set -euo pipefail
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          NEW_VER=$(npm version patch -m "chore: release v%s [skip ci]")
+
+          # Decide bump command
+          BUMP_CMD=""
+          case "${BUMP:-patch}" in
+            major|minor|patch)
+              if [ -n "${PREID:-}" ]; then
+                # Convert to pre* if preid provided
+                case "${BUMP}" in
+                  major) BUMP_CMD="npm version premajor --preid ${PREID} -m 'chore: release v%s [skip ci]'" ;;
+                  minor) BUMP_CMD="npm version preminor --preid ${PREID} -m 'chore: release v%s [skip ci]'" ;;
+                  patch) BUMP_CMD="npm version prepatch --preid ${PREID} -m 'chore: release v%s [skip ci]'" ;;
+                esac
+              else
+                BUMP_CMD="npm version ${BUMP} -m 'chore: release v%s [skip ci]'"
+              fi
+              ;;
+            none)
+              # No version bump; use existing version
+              BUMP_CMD="echo"
+              ;;
+            *)
+              echo "Unknown bump type: ${BUMP}" >&2
+              exit 1
+              ;;
+          esac
+
+          if [ "${BUMP}" = "none" ]; then
+            CURRENT_VER=$(node -p "require('./package.json').version")
+            NEW_VER="v${CURRENT_VER}"
+          else
+            # shellcheck disable=SC2086
+            NEW_VER=$(sh -lc "$BUMP_CMD")
+          fi
+
           echo "New version: $NEW_VER"
           git push --follow-tags
           

package/CHANGELOG.md

@@ -21,6 +21,39 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
+## [1.1.0] - 2025-09-18
+
+- **Added**
+  - field().upgrade() function now added to allow upgrades of older data sets to newer data.
+  - min/max/pattern/default FieldBuilder elements added for validation.
+  - Added new validator for language code BCP 47 format.
+  - Added new validator options for ISO DATE TIME filtering to Date or Time or Both
+  - Added new pre-built field() types including PII flags and validators for:
+    - email
+    - phone
+    - url
+    - uuid
+    - dateTimeISO
+    - dateISO
+    - timeISO
+    - richText
+    - generalText
+    - latitude
+    - longitude
+    - version
+    - countryCode
+    - languageCode
+  - New field().xxx tests for the above types.
+
+- **Changed**
+  - Updated CD Pipeline to accept a new param for version Major, Minor or Patch update
+
+- **Fixed**
+  - validateISODateTime for dateTime now accepts string matches that might not be the same as the date.toISOString() return value but are still valid ISO Date Time Strings.
+
+- **Security**
+  - (placeholder)
+
 ## [1.0.18] - 2025-09-17
 
 - **Fixed**
@@ -79,8 +112,9 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 
 ---
 
-[Unreleased]: https://github.com/Plasius-LTD/schema/compare/v1.0.18...HEAD
+[Unreleased]: https://github.com/Plasius-LTD/schema/compare/v1.1.0...HEAD
 [1.0.0]: https://github.com/Plasius-LTD/schema/releases/tag/v1.0.0
 [1.0.13]: https://github.com/Plasius-LTD/schema/releases/tag/v1.0.13
 [1.0.17]: https://github.com/Plasius-LTD/schema/releases/tag/v1.0.17
 [1.0.18]: https://github.com/Plasius-LTD/schema/releases/tag/v1.0.18
+[1.1.0]: https://github.com/Plasius-LTD/schema/releases/tag/v1.1.0

package/README.md

@@ -38,10 +38,149 @@ This ensures your local development environment matches the version used in CI/C
 
 ## Usage Example
 
-```js
+### Imports
+
+```ts
+import {
+  // core
+  createSchema,
+  field,
+  getSchemaForType,
+  getAllSchemas
+} from "@plasius/schema";
+```
+
+### 1) Define fields with the `field()` builder
+
+> Below uses the fluent builder exported via `field`/`field.builder`.
+
+```ts
+const UserFields = {
+  id: field.string().uuid().required().description("Unique user id"),
+  email: field.email().required(),
+  name: field.name().optional(),
+  age: field.number().int().min(0).optional(),
+  roles: field.array(field.string().enum(["admin", "user"]))
+            .default(["user"]).description("RBAC roles"),
+  createdAt: field.dateTimeISO().default(() => new Date()),
+};
+```
+
+Common methods (non‑exhaustive): `.required()`, `.optional()`, `.default(v|fn)`, `.description(text)`, and type‑specific helpers like `.email()`, `.uuid()`, `.min()`, `.max()`, `.enum([...])`.
+
+### 2) Create a **versioned** schema (enforces `type` + `version`)
+
+```ts
+export const UserSchema = createSchema({
+  entityType: "user",
+  version: "1.0.0",
+  fields: UserFields,
+});
 
+// Strongly-typed entity from a schema definition
+export type User = Infer<typeof UserSchema>;
 ```
 
+Schemas are discoverable at runtime if you register them during module init:
+
+```ts
+// later in app code
+const s = getSchemaForType("user"); // returns UserSchema
+const all = getAllSchemas(); // Map<string, Map<string, Schema>> or similar
+```
+
+### 3) Validate data against the schema
+
+```ts
+const raw = {
+  type: "user",
+  version: "1.0.0",
+  id: crypto.randomUUID(),
+  email: "alice@example.com",
+};
+
+const result = UserSchemavalidate(raw);
+if (result.valid && result.errors.length == 0) {
+  // result.value is typed as User
+  const user: User = result.value;
+} else {
+  // result.errors: ValidationError[] (path/code/message)
+  console.error(result.errors);
+}
+```
+
+> If your validation layer also exposes a throwing variant (e.g. `validateOrThrow(UserSchema, raw)`), you can use that in places where exceptions are preferred.
+
+### 4) Version enforcement in action
+
+If either `type` or `version` doesn’t match the schema, validation fails.
+
+```ts
+const wrong = { type: "User", version: "2.0.0", id: "123", email: "x@x" };
+const bad = UserSchema.validate(wrong);
+// bad.valid === false; errors will include mismatches for type/version
+```
+
+### 5) Evolving your schema
+
+Keep new versions side‑by‑side and migrate at edges:
+
+```ts
+export const UserV2 = createSchema({
+  entityType: "user",
+  version: "2.0.0",
+  fields: {
+    ...UserFields,
+    displayName: field.string().min(1).max(100).optional(),
+  },
+});
+```
+
+> Write a small migration function in your app to transform `User (1.0.0)` → `User (2.0.0)` where needed.
+
+### 6) Field-level upgrades
+
+The schema supports a new `.upgrade()` method on fields to define field-level upgrade logic. This is useful when tightening restrictions on a field, such as reducing maximum length, strengthening format constraints, or normalizing values, without changing the field’s overall shape.
+
+For example, suppose a `displayName` field previously allowed strings up to 60 characters, but you want to reduce the max length to 55 characters and normalize whitespace by trimming and collapsing spaces. You can define an upgrader function that attempts to fix old values to meet the new constraints:
+
+```ts
+const UserV3Fields = {
+  ...UserFields,
+  displayName: field.string().max(55).optional()
+    .upgrade((oldValue) => {
+      if (typeof oldValue !== "string") {
+        return { ok: false, error: "Expected string" };
+      }
+      // Normalize whitespace: trim and collapse multiple spaces
+      const normalized = oldValue.trim().replace(/\s+/g, " ");
+      if (normalized.length > 55) {
+        return { ok: false, error: "Display name too long after normalization" };
+      }
+      return { ok: true, value: normalized };
+    }),
+};
+
+export const UserV3 = createSchema({
+  entityType: "user",
+  version: "3.0.0",
+  fields: UserV3Fields,
+});
+```
+
+Other typical upgrade strategies include:
+
+- Clamping numeric values to new min/max bounds
+- Remapping enum values to new sets or keys
+- Normalizing whitespace or case in strings
+- Converting deprecated flag values to new formats
+
+During validation, if the entity version is less than the schema version and the field's value fails validation, the upgrader function will be invoked to attempt to transform the old value into a valid new value. If the upgrade succeeds and the transformed value passes validation, the upgraded value is used. If the upgrade fails or the transformed value still does not validate, validation errors will be returned.
+
+**Note:** Field-level upgrades only run when the schema version is greater than the entity version and the field validation initially fails. This provides a convenient way to handle incremental field changes without requiring full schema migrations.
+
+You can still write schema-level migration functions for larger or more complex changes that affect multiple fields or require more extensive transformation logic. Field-level upgrades complement these by handling simpler, localized upgrades directly within the schema definition.
+
 ---
 
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/schema",
-  "version": "1.0.18",
+  "version": "1.1.0",
   "description": "Entity schema definition & validation helpers for Plasius ecosystem",
   "type": "module",
   "main": "./dist/index.cjs",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:5e59b78b-f6f8-47c0-8329-d6447041544f",
+  "serialNumber": "urn:uuid:329219f1-3f86-497c-9d0e-3dc025a3a272",
   "version": 1,
   "metadata": {
-    "timestamp": "2025-09-17T16:14:58.925Z",
+    "timestamp": "2025-09-18T14:38:35.724Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@plasius/schema@1.0.18",
+      "bom-ref": "@plasius/schema@1.1.0",
       "type": "library",
       "name": "schema",
-      "version": "1.0.18",
+      "version": "1.1.0",
       "scope": "required",
       "author": "Plasius LTD",
       "description": "Entity schema definition & validation helpers for Plasius ecosystem",
-      "purl": "pkg:npm/%40plasius/schema@1.0.18",
+      "purl": "pkg:npm/%40plasius/schema@1.1.0",
       "properties": [
         {
           "name": "cdx:npm:package:path",
@@ -59,7 +59,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@plasius/schema@1.0.18",
+      "ref": "@plasius/schema@1.1.0",
       "dependsOn": []
     }
   ]

package/src/field.builder.ts

@@ -11,7 +11,17 @@ export class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
   isRequired = true;
   _validator?: (value: any) => boolean;
   _description: string = "";
-  _version: string = "1.0";
+  _version: string = "1.0.0";
+  _default?: TInternal | (() => TInternal);
+  _upgrade?: (
+    value: any,
+    ctx: {
+      entityFrom: string;
+      entityTo: string;
+      fieldTo: string;
+      fieldName: string;
+    }
+  ) => { ok: boolean; value?: any; error?: string };
   _shape?: Record<string, FieldBuilder<any>>;
   itemType?: FieldBuilder<any>;
   refType?: string;
@@ -68,6 +78,41 @@ export class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     return this;
   }
 
+  default(
+    value: TInternal | (() => TInternal)
+  ): FieldBuilder<TExternal, TInternal> {
+    this._default = value;
+    // Supplying a default implies the value may be omitted at input time.
+    // Do not couple defaulting with validation.
+    this.isRequired = false;
+    return this;
+  }
+
+  /**
+   * Configure an upgrader used when validating older entities against a newer schema.
+   * The upgrader receives the current field value and version context, and should
+   * return { ok: true, value } with the upgraded value, or { ok: false, error }.
+   */
+  upgrade(
+    fn: (
+      value: any,
+      ctx: {
+        entityFrom: string;
+        entityTo: string;
+        fieldTo: string;
+        fieldName: string;
+      }
+    ) => { ok: boolean; value?: any; error?: string }
+  ): FieldBuilder<TExternal, TInternal> {
+    this._upgrade = fn;
+    return this;
+  }
+
+  getDefault(): TInternal | undefined {
+    const v = this._default;
+    return typeof v === "function" ? (v as () => TInternal)() : v;
+  }
+
   version(ver: string): FieldBuilder<TExternal, TInternal> {
     this._version = ver;
     return this;
@@ -80,6 +125,72 @@ export class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     return this;
   }
 
+  min(min: number): FieldBuilder<TExternal, TInternal> {
+    if (this.type === "number") {
+      const prevValidator = this._validator;
+      this._validator = (value: any) => {
+        const valid = typeof value === "number" && value >= min;
+        return prevValidator ? prevValidator(value) && valid : valid;
+      };
+    } else if (this.type === "string") {
+      const prevValidator = this._validator;
+      this._validator = (value: any) => {
+        const valid = typeof value === "string" && value.length >= min;
+        return prevValidator ? prevValidator(value) && valid : valid;
+      };
+    } else if (this.type === "array") {
+      const prevValidator = this._validator;
+      this._validator = (value: any) => {
+        const valid = Array.isArray(value) && value.length >= min;
+        return prevValidator ? prevValidator(value) && valid : valid;
+      };
+    } else {
+      throw new Error(
+        "Min is only supported on number, string, or array fields."
+      );
+    }
+    return this;
+  }
+
+  max(max: number): FieldBuilder<TExternal, TInternal> {
+    if (this.type === "number") {
+      const prevValidator = this._validator;
+      this._validator = (value: any) => {
+        const valid = typeof value === "number" && value <= max;
+        return prevValidator ? prevValidator(value) && valid : valid;
+      };
+    } else if (this.type === "string") {
+      const prevValidator = this._validator;
+      this._validator = (value: any) => {
+        const valid = typeof value === "string" && value.length <= max;
+        return prevValidator ? prevValidator(value) && valid : valid;
+      };
+    } else if (this.type === "array") {
+      const prevValidator = this._validator;
+      this._validator = (value: any) => {
+        const valid = Array.isArray(value) && value.length <= max;
+        return prevValidator ? prevValidator(value) && valid : valid;
+      };
+    } else {
+      throw new Error(
+        "Max is only supported on number, string, or array fields."
+      );
+    }
+    return this;
+  }
+
+  pattern(regex: RegExp): FieldBuilder<TExternal, TInternal> {
+    if (this.type !== "string") {
+      throw new Error("Pattern is only supported on string fields.");
+    }
+    const prevValidator = this._validator;
+    this._validator = (value: any) => {
+      const valid = typeof value === "string" && regex.test(value);
+      return prevValidator ? prevValidator(value) && valid : valid;
+    };
+    return this;
+  }
+
   enum<const U extends readonly TInternal[]>(
     values: U
   ): FieldBuilder<U[number]> {
@@ -99,10 +210,16 @@ export class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     return this as any;
   }
 
+  /**
+   * Create a shallow clone with a different external type parameter.
+   * Note: shape and itemType are passed by reference (shallow). If you need
+   * deep isolation of nested FieldBuilders, clone them explicitly.
+   */
   as<U>(): FieldBuilder<U, TInternal> {
     const clone = new FieldBuilder<U, TInternal>(this.type, {
       shape: this._shape,
       itemType: this.itemType,
+      refType: this.refType,
     });
     clone.enumValues = this.enumValues;
     clone.isImmutable = this.isImmutable;
@@ -112,6 +229,9 @@ export class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     clone._version = this._version;
     clone._pii = this._pii;
     clone._validator = this._validator as any;
+    clone._default = this._default as any;
+    clone._upgrade = this._upgrade;
+    // refType already provided in constructor options above
     return clone;
   }
 }

package/src/field.ts

@@ -1,6 +1,19 @@
+import { version } from "os";
 import { FieldBuilder } from "./field.builder.js";
 import { Infer } from "./infer.js";
 import { SchemaShape } from "./types.js";
+import {
+  validateCountryCode,
+  validateDateTimeISO,
+  validateEmail,
+  validatePhone,
+  validateRichText,
+  validateSafeText,
+  validateSemVer,
+  validateUrl,
+  validateUUID,
+} from "./validation/index.js";
+import { validateLanguage } from "./validation/languageCode.BCP47.js";
 
 export const field = {
   string: () => new FieldBuilder<string>("string"),
@@ -11,4 +24,130 @@ export const field = {
   array: (itemType: FieldBuilder) => new FieldBuilder("array", { itemType }),
   ref: <S extends SchemaShape>(refType: string) =>
     new FieldBuilder<Infer<S>>("ref", { refType }),
+  email: () =>
+    new FieldBuilder<string>("string")
+      .validator(validateEmail)
+      .PID({
+        classification: "high",
+        action: "encrypt",
+        logHandling: "redact",
+        purpose: "an email address",
+      })
+      .description("An email address"),
+  phone: () =>
+    new FieldBuilder<string>("string")
+      .validator(validatePhone)
+      .PID({
+        classification: "high",
+        action: "encrypt",
+        logHandling: "redact",
+        purpose: "a phone number",
+      })
+      .description("A phone number"),
+  url: () =>
+    new FieldBuilder<string>("string")
+      .validator(validateUrl)
+      .PID({
+        classification: "low",
+        action: "hash",
+        logHandling: "pseudonym",
+        purpose: "a URL",
+      })
+      .description("A URL"),
+  uuid: () =>
+    new FieldBuilder<string>("string")
+      .PID({
+        classification: "low",
+        action: "hash",
+        logHandling: "pseudonym",
+        purpose: "a UUID",
+      })
+      .validator(validateUUID)
+      .description("A UUID"),
+  dateTimeISO: () =>
+    new FieldBuilder<string>("string")
+      .PID({
+        classification: "none",
+        action: "none",
+        logHandling: "plain",
+        purpose: "a date string",
+      })
+      .validator(validateDateTimeISO)
+      .description("A date string in ISO 8601 format"),
+  dateISO: () =>
+    new FieldBuilder<string>("string")
+      .PID({
+        classification: "none",
+        action: "none",
+        logHandling: "plain",
+        purpose: "a date string",
+      })
+      .validator((s) => validateDateTimeISO(s, { mode: "date" }))
+      .description("A date string in ISO 8601 format (date only)"),
+  timeISO: () =>
+    new FieldBuilder<string>("string")
+      .PID({
+        classification: "none",
+        action: "none",
+        logHandling: "plain",
+        purpose: "a time string",
+      })
+      .validator((s) => validateDateTimeISO(s, { mode: "time" }))
+      .description("A time string in ISO 8601 format (time only)"),
+  richText: () =>
+    new FieldBuilder<string>("string")
+      .PID({
+        classification: "low",
+        action: "clear",
+        logHandling: "omit",
+        purpose: "rich text content",
+      })
+      .validator(validateRichText)
+      .description("Rich text content, may include basic HTML formatting"),
+  generalText: () =>
+    new FieldBuilder<string>("string")
+      .PID({
+        classification: "none",
+        action: "none",
+        logHandling: "plain",
+        purpose: "Plain text content",
+      })
+      .validator(validateSafeText)
+      .description("Standard text content, no HTML allowed"),
+  latitude: () =>
+    new FieldBuilder<number>("number")
+      .PID({
+        classification: "low",
+        action: "clear",
+        logHandling: "omit",
+        purpose: "Latitude in decimal degrees, WGS 84 (ISO 6709)",
+      })
+      .min(-90)
+      .max(90)
+      .description("Latitude in decimal degrees, WGS 84 (ISO 6709)"),
+  longitude: () =>
+    new FieldBuilder<number>("number")
+      .PID({
+        classification: "low",
+        action: "clear",
+        logHandling: "omit",
+        purpose: "Longitude in decimal degrees, WGS 84 (ISO 6709)",
+      })
+      .min(-180)
+      .max(180)
+      .description("Longitude in decimal degrees, WGS 84 (ISO 6709)"),
+  version: () =>
+    new FieldBuilder<string>("string")
+      .validator(validateSemVer)
+      .description("A semantic version string, e.g. '1.0.0'"),
+  countryCode: () =>
+    new FieldBuilder<string>("string")
+      .validator(validateCountryCode)
+      .description("An ISO 3166 country code, e.g. 'US', 'GB', 'FR'"),
+  languageCode: () =>
+    new FieldBuilder<string>("string")
+      .validator(validateLanguage)
+      .description(
+        "An BCP 47 structured language code, primarily ISO 639-1 and optionally with ISO 3166-1 alpha-2 country code, e.g. 'en', 'en-US', 'fr', 'fr-FR'"
+      ),
 };