@plasius/schema 1.0.17 → 1.1.0

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'"
+      ),
 };

package/src/schema.ts

@@ -11,9 +11,22 @@ import {
   scrubPiiForDelete as piiScrubPiiForDelete,
 } from "./pii.js";
 import { FieldBuilder } from "./field.builder.js";
+import { validateSemVer } from "./validation/version.SEMVER2.0.0.js";
 
 const globalSchemaRegistry = new Map<string, Schema<any>>();
 
+function cmpSemver(a: string, b: string): number {
+  const pa = a.split(".").map((n) => parseInt(n, 10));
+  const pb = b.split(".").map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const ai = pa[i] ?? 0;
+    const bi = pb[i] ?? 0;
+    if (ai > bi) return 1;
+    if (ai < bi) return -1;
+  }
+  return 0;
+}
+
 function validateEnum(
   parentKey: string,
   value: any,
@@ -469,7 +482,7 @@ export function createSchema<S extends SchemaShape>(
   _shape: S,
   entityType: string,
   options: SchemaOptions = {
-    version: "1.0",
+    version: "1.0.0",
     table: "",
     schemaValidator: () => true,
     piiEnforcement: "none",
@@ -477,10 +490,10 @@ export function createSchema<S extends SchemaShape>(
 ): Schema<S> {
   const systemFields = {
     type: field.string().immutable().system(),
-    version: field.string().immutable().system(),
+    version: field.string().immutable().system().validator(validateSemVer),
   };
 
-  const version = options.version || "1.0";
+  const version = options.version || "1.0.0";
   const store = options.table || "";
   const schema: Schema<S> = {
     // 🔗 Define the schema shape
@@ -541,18 +554,72 @@ export function createSchema<S extends SchemaShape>(
         );
         if (shortCircuit) continue;
 
-        // 4) Custom validator
-        const { invalid } = runCustomValidator("", key, value, def, errors);
-        if (invalid) continue;
+        // A local validator for this field that returns errors instead of pushing into the outer array
+        const validateField = (val: any): string[] => {
+          const localErrors: string[] = [];
+          const { invalid } = runCustomValidator(
+            "",
+            key,
+            val,
+            def,
+            localErrors
+          );
+          if (!invalid) {
+            validateByType("", key, val, def, localErrors);
+          }
+          return localErrors;
+        };
 
-        // 5) Type-specific validation
-        validateByType("", key, value, def, errors);
+        // First pass validation
+        let fieldValue = value;
+        let fieldErrors = validateField(fieldValue);
+
+        // Attempt upgrade if invalid and an upgrader exists and entity is older than schema
+        const entityFrom = String(working.version ?? "0.0.0");
+        const entityTo = String(version);
+        const fieldTo = String((def as any)._version ?? entityTo);
+        const hasUpgrader = typeof (def as any)._upgrade === "function";
+
+        if (
+          fieldErrors.length > 0 &&
+          hasUpgrader &&
+          cmpSemver(entityFrom, entityTo) < 0
+        ) {
+          const up = (def as any)._upgrade as (
+            value: any,
+            ctx: {
+              entityFrom: string;
+              entityTo: string;
+              fieldTo: string;
+              fieldName: string;
+            }
+          ) => { ok: boolean; value?: any; error?: string };
+
+          const res = up(fieldValue, {
+            entityFrom,
+            entityTo,
+            fieldTo,
+            fieldName: key,
+          });
+          if (res && res.ok) {
+            fieldValue = res.value;
+            fieldErrors = validateField(fieldValue);
+          } else {
+            fieldErrors.push(
+              res?.error ||
+                `Failed to upgrade field ${key} from v${entityFrom} to v${entityTo}`
+            );
+          }
+        }
 
-        // Assign value regardless; storage transforms happen elsewhere
-        result[key] = value;
+        result[key] = fieldValue;
+        // Apply or record errors
+        if (fieldErrors.length !== 0) {
+          errors.push(...fieldErrors);
+          continue;
+        }
       }
 
-
       if (errors.length === 0 && options.schemaValidator) {
         const castValue = result as Infer<S>;
         if (!options.schemaValidator(castValue)) {

package/src/validation/dateTime.ISO8601.ts

@@ -1,9 +1,60 @@
 /**
- * Validates whether a string is a properly formatted ISO 8601 datetime.
- * Ensures the string parses as a valid Date and matches the canonical toISOString() format.
+ * Validates whether a string is a properly formatted ISO 8601 datetime, date, or time.
+ * 
+ * @param value - The value to validate.
+ * @param options - Optional settings for validation mode.
+ * @param options.mode - The mode of validation:
+ *   - "datetime" (default): Checks full ISO 8601 datetime and equality with toISOString().
+ *   - "date": Validates that the string is in YYYY-MM-DD format and represents a valid date.
+ *   - "time": Validates that the string matches a valid HH:MM:SS(.sss)?Z? ISO 8601 time pattern.
+ * @returns True if the value is valid according to the specified mode; otherwise, false.
  */
-export const validateDateTimeISO = (value: unknown): boolean => {
+export const validateDateTimeISO = (
+  value: unknown,
+  options?: { mode?: "datetime" | "date" | "time" }
+): boolean => {
+  const mode = options?.mode ?? "datetime";
+
   if (typeof value !== "string") return false;
-  const date = new Date(value);
-  return !isNaN(date.getTime()) && value === date.toISOString();
+
+  if (mode === "datetime") {
+    // Strict ISO 8601 date-time: YYYY-MM-DDTHH:mm:ss(.fraction)?(Z|±HH:MM)
+    const isoDateTimeRegex =
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+    if (!isoDateTimeRegex.test(value)) return false;
+
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) return false;
+
+    // We purposely do NOT require `value === date.toISOString()` because
+    // valid ISO8601 inputs may include offsets (e.g., "+01:00") or omit
+    // milliseconds, both of which produce a different canonical ISO string.
+    // The regex ensures strict shape; Date parsing ensures it is a real moment.
+    return true;
+  }
+
+  if (mode === "date") {
+    // YYYY-MM-DD format
+    const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
+    if (!dateRegex.test(value)) return false;
+    const date = new Date(value);
+    if (isNaN(date.getTime())) return false;
+    // Ensure the date parts match exactly (to avoid 2023-02-30 being accepted)
+    const [year, month, day] = value.split("-").map(Number);
+    return (
+      date.getUTCFullYear() === year &&
+      date.getUTCMonth() + 1 === month &&
+      date.getUTCDate() === day
+    );
+  }
+
+  if (mode === "time") {
+    // HH:MM:SS(.sss)?Z?
+    // Hours: 00-23, Minutes: 00-59, Seconds: 00-59, optional fractional seconds, optional Z
+    const timeRegex = /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?Z?$/;
+    return timeRegex.test(value);
+  }
+
+  return false;
 };

package/src/validation/languageCode.BCP47.ts

@@ -0,0 +1,299 @@
+/* eslint-disable @typescript-eslint/consistent-type-assertions */
+
+/**
+ * ISO 639-1 language codes (two-letter).
+ * Tip: Keep this list as source of truth for supported languages in your app.
+ */
+export enum IsoLanguageCode {
+  Afar = "aa",
+  Abkhazian = "ab",
+  Afrikaans = "af",
+  Akan = "ak",
+  Albanian = "sq",
+  Amharic = "am",
+  Arabic = "ar",
+  Aragonese = "an",
+  Armenian = "hy",
+  Assamese = "as",
+  Avaric = "av",
+  Aymara = "ay",
+  Azerbaijani = "az",
+  Bashkir = "ba",
+  Bambara = "bm",
+  Basque = "eu",
+  Belarusian = "be",
+  Bengali = "bn",
+  Bislama = "bi",
+  Bosnian = "bs",
+  Breton = "br",
+  Bulgarian = "bg",
+  Burmese = "my",
+  Catalan = "ca",
+  Chamorro = "ch",
+  Chechen = "ce",
+  Chinese = "zh",
+  ChurchSlavic = "cu",
+  Chuvash = "cv",
+  Cornish = "kw",
+  Corsican = "co",
+  Cree = "cr",
+  Croatian = "hr",
+  Czech = "cs",
+  Danish = "da",
+  Divehi = "dv",
+  Dutch = "nl",
+  Dzongkha = "dz",
+  English = "en",
+  Esperanto = "eo",
+  Estonian = "et",
+  Ewe = "ee",
+  Faroese = "fo",
+  Fijian = "fj",
+  Finnish = "fi",
+  French = "fr",
+  WesternFrisian = "fy",
+  Fulah = "ff",
+  Gaelic = "gd",
+  Galician = "gl",
+  Ganda = "lg",
+  Georgian = "ka",
+  German = "de",
+  Greek = "el",
+  Kalaallisut = "kl",
+  Guarani = "gn",
+  Gujarati = "gu",
+  Haitian = "ht",
+  Hausa = "ha",
+  Hebrew = "he",
+  Herero = "hz",
+  Hindi = "hi",
+  HiriMotu = "ho",
+  Hungarian = "hu",
+  Icelandic = "is",
+  Ido = "io",
+  Igbo = "ig",
+  Indonesian = "id",
+  Interlingua = "ia",
+  Interlingue = "ie",
+  Inuktitut = "iu",
+  Inupiaq = "ik",
+  Irish = "ga",
+  Italian = "it",
+  Japanese = "ja",
+  Javanese = "jv",
+  Kannada = "kn",
+  Kanuri = "kr",
+  Kashmiri = "ks",
+  Kazakh = "kk",
+  CentralKhmer = "km",
+  Kikuyu = "ki",
+  Kinyarwanda = "rw",
+  Kyrgyz = "ky",
+  Komi = "kv",
+  Kongo = "kg",
+  Korean = "ko",
+  Kuanyama = "kj",
+  Kurdish = "ku",
+  Lao = "lo",
+  Latin = "la",
+  Latvian = "lv",
+  Limburgan = "li",
+  Lingala = "ln",
+  Lithuanian = "lt",
+  LubaKatanga = "lu",
+  Luxembourgish = "lb",
+  Macedonian = "mk",
+  Malagasy = "mg",
+  Malay = "ms",
+  Malayalam = "ml",
+  Maltese = "mt",
+  Manx = "gv",
+  Maori = "mi",
+  Marathi = "mr",
+  Marshallese = "mh",
+  Mongolian = "mn",
+  Nauru = "na",
+  Navajo = "nv",
+  NorthNdebele = "nd",
+  SouthNdebele = "nr",
+  Ndonga = "ng",
+  Nepali = "ne",
+  Norwegian = "no",
+  NorwegianBokmal = "nb",
+  NorwegianNynorsk = "nn",
+  SichuanYi = "ii",
+  Occitan = "oc",
+  Ojibwa = "oj",
+  Oriya = "or",
+  Oromo = "om",
+  Ossetian = "os",
+  Pali = "pi",
+  Pashto = "ps",
+  Persian = "fa",
+  Polish = "pl",
+  Portuguese = "pt",
+  Punjabi = "pa",
+  Quechua = "qu",
+  Romansh = "rm",
+  Romanian = "ro",
+  Rundi = "rn",
+  Russian = "ru",
+  Samoan = "sm",
+  Sango = "sg",
+  Sanskrit = "sa",
+  Sardinian = "sc",
+  Serbian = "sr",
+  Shona = "sn",
+  Sindhi = "sd",
+  Sinhala = "si",
+  Slovak = "sk",
+  Slovenian = "sl",
+  Somali = "so",
+  SouthernSotho = "st",
+  Spanish = "es",
+  Sundanese = "su",
+  Swahili = "sw",
+  Swati = "ss",
+  Swedish = "sv",
+  Tagalog = "tl",
+  Tahitian = "ty",
+  Tajik = "tg",
+  Tamil = "ta",
+  Tatar = "tt",
+  Telugu = "te",
+  Thai = "th",
+  Tibetan = "bo",
+  Tigrinya = "ti",
+  Tonga = "to",
+  Tsonga = "ts",
+  Tswana = "tn",
+  Turkish = "tr",
+  Turkmen = "tk",
+  Twi = "tw",
+  Uighur = "ug",
+  Ukrainian = "uk",
+  Urdu = "ur",
+  Uzbek = "uz",
+  Venda = "ve",
+  Vietnamese = "vi",
+  Volapuk = "vo",
+  Walloon = "wa",
+  Welsh = "cy",
+  Wolof = "wo",
+  Xhosa = "xh",
+  Yiddish = "yi",
+  Yoruba = "yo",
+  Zhuang = "za",
+  Zulu = "zu",
+}
+
+/** Fast lookup set for enum values (lowercase 2-letter codes). */
+const ISO_LANGUAGE_SET: ReadonlySet<string> = new Set<string>(
+  Object.values(IsoLanguageCode)
+);
+
+/** Type guard: primary language must be one of the enum values. */
+export function isIsoLanguageCode(value: unknown): value is IsoLanguageCode {
+  return typeof value === "string" && ISO_LANGUAGE_SET.has(value.toLowerCase());
+}
+
+/**
+ * Region validator per BCP 47:
+ * - ISO 3166-1 alpha-2: 2 uppercase letters (e.g., GB, US)
+ * - UN M.49 numeric: 3 digits (e.g., 419 for Latin America)
+ *
+ * NOTE: This validates *shape* not membership against the 3166 list.
+ * If you want hard membership, we can add a Set of all alpha-2 regions.
+ */
+export function isRegionSubtag(value: string): boolean {
+  return /^[A-Z]{2}$/.test(value) || /^\d{3}$/.test(value);
+}
+
+/** Script subtag per ISO 15924: one capital + three lowercase (e.g., Latn, Cyrl, Hans). */
+export function isScriptSubtag(value: string): boolean {
+  return /^[A-Z][a-z]{3}$/.test(value);
+}
+
+/** Variant subtag per BCP 47: 5–8 alnum, or 4 starting with a digit. */
+export function isVariantSubtag(value: string): boolean {
+  return /^([0-9][A-Za-z0-9]{3}|[A-Za-z0-9]{5,8})$/.test(value);
+}
+
+/** Extension sequence: singleton (alnum except 'x') + one or more 2–8 alnum subtags. */
+export function isExtensionSingleton(value: string): boolean {
+  return /^[0-9A-WY-Za-wy-z]$/.test(value); // any alnum except 'x' (private-use)
+}
+export function isExtensionSubtag(value: string): boolean {
+  return /^[A-Za-z0-9]{2,8}$/.test(value);
+}
+
+/** Private-use subtag: 'x' then one or more 1–8 alnum subtags. */
+export function isPrivateUseSingleton(value: string): boolean {
+  return value.toLowerCase() === "x";
+}
+export function isPrivateUseSubtag(value: string): boolean {
+  return /^[A-Za-z0-9]{1,8}$/.test(value);
+}
+
+/**
+ * Validates:
+ *  - plain language: "en"
+ *  - language + region: "en-GB"
+ *  - language + script + region: "sr-Cyrl-RS"
+ *  - language + variants: "sl-rozaj-biske", "de-CH-1996"
+ *  - extensions: "en-GB-u-ca-gregory"
+ *  - private-use: "en-x-klingon" or just "x-piglatin"
+ *
+ * Returns true only if the primary language is in IsoLanguageCode
+ * and the rest of the tag conforms to BCP 47 structure.
+ */
+export function validateLanguage(value: unknown): boolean {
+  if (typeof value !== "string" || value.length === 0) return false;
+
+  const parts = value.split("-");
+  let i = 0;
+
+  // 1) primary language (must be enum member; we use lowercase for comparison)
+  const lang = parts[i];
+  if (!lang || !isIsoLanguageCode(lang)) return false;
+  i += 1;
+
+  // 2) optional script
+  if (i < parts.length && isScriptSubtag(parts[i] as string)) {
+    i += 1;
+  }
+
+  // 3) optional region
+  if (i < parts.length && isRegionSubtag((parts[i] as string).toUpperCase())) {
+    // region must be uppercase if alpha; we normalize for check only
+    i += 1;
+  }
+
+  // 4) zero or more variants
+  while (i < parts.length && isVariantSubtag((parts[i] as string))) {
+    i += 1;
+  }
+
+  // 5) zero or more extensions
+  //    extension = singleton ; 2–8 ; ( ; 2–8 )*
+  while (i < parts.length && isExtensionSingleton((parts[i] as string))) {
+    i += 1;
+    // must have at least one following subtag of length 2–8
+    if (!(i < parts.length && isExtensionSubtag(parts[i]!))) return false;
+    while (i < parts.length && isExtensionSubtag(parts[i]!)) {
+      i += 1;
+    }
+  }
+
+  // 6) optional private-use: 'x' 1*('-' (1*8alnum))
+  if (i < parts.length && isPrivateUseSingleton(parts[i]!)) {
+    i += 1;
+    if (!(i < parts.length && isPrivateUseSubtag(parts[i]!))) return false;
+    while (i < parts.length && isPrivateUseSubtag(parts[i]!)) {
+      i += 1;
+    }
+  }
+
+  // no leftovers
+  return i === parts.length;
+}

package/src/validation/version.SEMVER2.0.0.ts

@@ -4,5 +4,7 @@
  */
 export function validateSemVer(value: unknown): boolean {
   if (typeof value !== "string") return false;
-  return /^(\d+)\.(\d+)\.(\d+)$/.test(value);
+  return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/.test(
+    value
+  );
 }