@plasius/schema 1.1.0 → 1.1.1

package/legal/INDIVIDUAL_CLA.md

@@ -1,91 +0,0 @@
-# Individual Contributor License Agreement (CLA)
-
-**Project:** @plasius/schema (Plasius LTD)  
-**Version:** 1.0 — 2025‑09‑12  
-**Contact:** [contributors@plasius.co.uk](mailto:contributors@plasius.co.uk)
-
----
-
-## 1. Definitions
-
-- **"You"** (or **"Contributor"**) means the individual signing this CLA and submitting Contributions to the Project.
-- **"Contribution"** means any original work of authorship, including code, documentation, data, designs, or feedback that You submit to the Project in any form (e.g., pull request, issue comment, email, file upload).
-- **"Project"** means the @plasius/schema repositories and related materials owned or managed by **Plasius LTD**.
-
-## 2. Copyright License Grant
-
-You hereby grant to Plasius LTD a **perpetual, worldwide, non‑exclusive, transferable, sublicensable, royalty‑free, irrevocable** copyright license to:
-
-- use, reproduce, publicly display, publicly perform, modify, create derivative works of, and
-- distribute Contributions in source and object form,
-- and to **sublicense** these rights under any terms Plasius LTD chooses, including proprietary or open‑source licenses.
-
-## 3. Patent License Grant
-
-You hereby grant to Plasius LTD and its sublicensees a **perpetual, worldwide, non‑exclusive, transferable, royalty‑free, irrevocable** patent license to **make, have made, use, offer to sell, sell, import, and otherwise transfer** the Contribution and derivative works thereof, where such license applies only to patent claims that You **own or control** and that would be infringed by Your Contribution or its combination with the Project.
-
-## 4. Moral Rights & Attribution
-
-To the maximum extent permitted by applicable law, You **waive** and agree not to assert any moral rights (e.g., rights of attribution or integrity) in or to the Contribution against Plasius LTD. Plasius LTD may, but is not required to, credit You.
-
-## 5. Representations & Warranties
-
-You represent that:
-
-1. **Originality / Rights:** Each Contribution is Your original creation, or You have sufficient rights to submit it and grant the licenses above.
-2. **No Confidential Info:** Contributions **do not** include confidential information or trade secrets of any third party.
-3. **No Infringement:** To the best of Your knowledge, Contributions do not infringe any third‑party IP rights.
-4. **Employment / Contractor Status:** If Your employer or a third party might claim rights in Your Contribution, You have obtained **written permission** to make the Contribution and grant these licenses (attach or reference below), or Your Contribution is made **outside the scope** of your employment and without using your employer’s confidential information or resources.
-5. **Compliance:** You will follow the Project’s policies (e.g., Code of Conduct, Security Policy) and applicable laws.
-
-## 6. Third‑Party Code
-
-If Your Contribution includes code, data, or other material from a third party, You will **identify the material and its license** in the pull request or submission, and ensure it is **compatible** with the Project’s licensing model. You will not submit material subject to terms that require the Project to disclose proprietary source code (e.g., certain copyleft obligations) unless the Project has **pre‑approved** such inclusion in writing.
-
-## 7. Scope & Duration
-
-- This CLA covers **all past and future** Contributions You submit to the Project, unless and until You provide written notice to **revoke** it.
-- Revocation is **not retroactive**: rights granted for prior Contributions remain in effect.
-
-## 8. Disclaimer
-
-THE CONTRIBUTION IS PROVIDED “AS IS” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON‑INFRINGEMENT.
-
-## 9. Governing Law & Jurisdiction
-
-This CLA is governed by the **laws of England and Wales**, and the courts of England and Wales shall have **exclusive jurisdiction** over any dispute arising out of or relating to it.
-
-## 10. Entire Agreement
-
-This CLA is the entire agreement between You and Plasius LTD regarding Contributions. It supersedes any prior discussions relating to Contributions. If any provision is held unenforceable, the remaining provisions remain in full force.
-
----
-
-## 11. Contributor Information & Signature
-
-By signing below, You agree to the terms of this CLA for Your Contributions to the Project.
-
-**Full Name:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-**Email:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-**GitHub Handle:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-**Address (optional):** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-**Employer (if applicable):** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-**If employed:** ☐ I confirm Contributions are made outside the scope of employment **or** ☐ I have attached my employer’s written permission.
-
-**Signature:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-**Date (YYYY‑MM‑DD):** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-_Electronic signatures are accepted. You may type your name in the Signature field and email a PDF copy._
-
-**Submission:** Please email the signed CLA to **[contributors@plasius.co.uk](mailto:contributors@plasius.co.uk)** with subject line: `CLA – Individual – <GitHubHandle>`.
-
-**(Optional) Attachments / Notes:**
-
-- Employer permission letter (if required)
-- Third‑party license disclosures (if any)

package/sbom.cdx.json

@@ -1,66 +0,0 @@
-{
-  "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
-  "bomFormat": "CycloneDX",
-  "specVersion": "1.5",
-  "serialNumber": "urn:uuid:329219f1-3f86-497c-9d0e-3dc025a3a272",
-  "version": 1,
-  "metadata": {
-    "timestamp": "2025-09-18T14:38:35.724Z",
-    "lifecycles": [
-      {
-        "phase": "build"
-      }
-    ],
-    "tools": [
-      {
-        "vendor": "npm",
-        "name": "cli",
-        "version": "10.9.3"
-      }
-    ],
-    "component": {
-      "bom-ref": "@plasius/schema@1.1.0",
-      "type": "library",
-      "name": "schema",
-      "version": "1.1.0",
-      "scope": "required",
-      "author": "Plasius LTD",
-      "description": "Entity schema definition & validation helpers for Plasius ecosystem",
-      "purl": "pkg:npm/%40plasius/schema@1.1.0",
-      "properties": [
-        {
-          "name": "cdx:npm:package:path",
-          "value": ""
-        }
-      ],
-      "externalReferences": [
-        {
-          "type": "vcs",
-          "url": "git+https://github.com/Plasius-LTD/schema.git"
-        },
-        {
-          "type": "website",
-          "url": "https://github.com/Plasius-LTD/schema#readme"
-        },
-        {
-          "type": "issue-tracker",
-          "url": "https://github.com/Plasius-LTD/schema/issues"
-        }
-      ],
-      "licenses": [
-        {
-          "license": {
-            "id": "Apache-2.0"
-          }
-        }
-      ]
-    }
-  },
-  "components": [],
-  "dependencies": [
-    {
-      "ref": "@plasius/schema@1.1.0",
-      "dependsOn": []
-    }
-  ]
-}

package/src/components.ts

@@ -1,39 +0,0 @@
-import { Infer } from "./infer.js";
-import { createSchema } from "./schema.js";
-import { Schema, SchemaShape } from "./types.js";
-// This module provides a registry for component schemas, allowing components to be registered and retrieved by type.
-const componentSchemaRegistry = new Map<string, Schema<SchemaShape>>();
-
-export function createComponentSchema<T extends SchemaShape>(
-  shape: SchemaShape,
-  name: string,
-  version: string,
-  tableName: string = "",
-  schemaValidator: (entity: Infer<T>) => boolean = () => true
-): Schema<SchemaShape> {
-  const schema = createSchema<T>(shape as T, name, {
-    version: version,
-    piiEnforcement: "strict",
-    table: tableName,
-    schemaValidator,
-  });
-  registerComponentSchema(name, schema as Schema<SchemaShape>);
-  return schema as Schema<SchemaShape>;
-}
-
-export function registerComponentSchema(
-  type: string,
-  schema: Schema<SchemaShape>
-) {
-  componentSchemaRegistry.set(type, schema);
-}
-
-export function getComponentSchema(
-  type: string
-): Schema<SchemaShape> | undefined {
-  return componentSchemaRegistry.get(type);
-}
-
-export function getAllComponentSchemas(): [string, Schema<SchemaShape>][] {
-  return Array.from(componentSchemaRegistry.entries());
-}

package/src/field.builder.ts

@@ -1,239 +0,0 @@
-type FieldType = "string" | "number" | "boolean" | "object" | "array" | "ref";
-
-import { type PII } from "./pii.js";
-import { getSchemaForType } from "./schema.js";
-
-export class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
-  _type!: TExternal;
-  _storageType!: TInternal;
-  isSystem = false;
-  isImmutable = false;
-  isRequired = true;
-  _validator?: (value: any) => boolean;
-  _description: string = "";
-  _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;
-  _pii: PII = {
-    classification: "none",
-    action: "none",
-    logHandling: "plain",
-    purpose: "an ordinary value",
-  };
-  enumValues?: readonly TInternal[];
-
-  constructor(
-    public type: FieldType,
-    options: {
-      shape?: Record<string, FieldBuilder<any>>;
-      itemType?: FieldBuilder<any>;
-      refType?: string;
-    } = {}
-  ) {
-    this._shape = options.shape;
-    this.itemType = options.itemType;
-    this.refType = options.refType;
-  }
-
-  immutable(): FieldBuilder<TExternal, TInternal> {
-    this.isImmutable = true;
-    return this;
-  }
-
-  system(): FieldBuilder<TExternal, TInternal> {
-    this.isSystem = true;
-    return this;
-  }
-
-  required(): FieldBuilder<TExternal, TInternal> {
-    this.isRequired = true;
-    return this;
-  }
-
-  optional(): FieldBuilder<TExternal, TInternal> {
-    this.isRequired = false;
-    return this;
-  }
-
-  validator(
-    fn: (value: TInternal) => boolean
-  ): FieldBuilder<TExternal, TInternal> {
-    this._validator = fn;
-    return this;
-  }
-
-  description(desc: string): FieldBuilder<TExternal, TInternal> {
-    this._description = desc;
-    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;
-  }
-
-  /// PID informs the schema PII handling of the manner in
-  /// which to handle data relating to this field.
-  PID(pii: PII): FieldBuilder<TExternal, TInternal> {
-    this._pii = pii;
-    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]> {
-    if (
-      this.type !== "string" &&
-      this.type !== "number" &&
-      !(
-        this.type === "array" &&
-        (this.itemType?.type === "string" || this.itemType?.type === "number")
-      )
-    ) {
-      throw new Error(
-        "Enums are only supported on string or number fields or arrays of strings or numbers."
-      );
-    }
-    this.enumValues = values;
-    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;
-    clone.isSystem = this.isSystem;
-    clone.isRequired = this.isRequired;
-    clone._description = this._description;
-    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;
-  }
-}
-
-export default FieldBuilder;

package/src/field.ts

@@ -1,153 +0,0 @@
-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"),
-  number: () => new FieldBuilder<number>("number"),
-  boolean: () => new FieldBuilder<boolean>("boolean"),
-  object: <T extends Record<string, FieldBuilder>>(fields: T) =>
-    new FieldBuilder<T>("object", { shape: fields }),
-  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'"
-      ),
-};

package/src/index.ts

@@ -1,7 +0,0 @@
-export type { Infer } from "./infer.js";
-export { field } from "./field.js";
-export { createSchema, getSchemaForType, getAllSchemas } from "./schema.js";
-export type * from "./types.js";
-export * from "./components.js";
-export * from "./validation/index.js";
-export * from "./field.builder.js";

package/src/infer.ts

@@ -1,34 +0,0 @@
-import { SchemaShape } from "./types.js";
-
-type InferField<T> = T extends { _type: infer U }
-  ? U
-  : T extends { type: "string" }
-    ? string
-    : T extends { type: "number" }
-      ? number
-      : T extends { type: "boolean" }
-        ? boolean
-        : T extends { type: "array"; itemType: infer Item }
-          ? InferField<Item>[]
-          : T extends { type: "object"; shape: infer Shape extends SchemaShape }
-            ? InferFromShape<Shape>
-            : unknown;
-
-type IsOptional<T> = T extends { optional: true } ? true : false;
-
-type InferFromShape<S extends SchemaShape> = {
-  [K in keyof S]: IsOptional<S[K]> extends true
-    ? InferField<S[K]> | undefined
-    : InferField<S[K]>;
-};
-
-type InferFromSchema<T extends { shape: SchemaShape }> = InferFromShape<
-  T["shape"]
->;
-
-type IsSchema<T> = T extends { shape: SchemaShape } ? true : false;
-
-export type Infer<T> =
-  IsSchema<T> extends true
-    ? InferFromSchema<T & { shape: SchemaShape }>
-    : InferFromShape<T & SchemaShape>;