@plasius/schema 1.0.0

package/src/types.ts

@@ -0,0 +1,156 @@
+import FieldBuilder from "./field.builder.js";
+import { Infer } from "./infer.js";
+import { PII, PIIAction, PIIClassification, PIILogHandling } from "./pii.js";
+
+export type FieldTypeMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  object: Record<string, unknown>;
+  "string[]": string[];
+  "number[]": number[];
+  "boolean[]": boolean[];
+  "object[]": Record<string, unknown>[];
+  ref: RefEntityId;
+  "ref[]": RefEntityId[];
+};
+
+export type FieldType = keyof FieldTypeMap;
+
+export type PIIEnforcement = "strict" | "warn" | "none";
+
+export interface SchemaOptions {
+  version?: string;
+  table?: string;
+  schemaValidator?: (value: any) => boolean;
+  piiEnforcement?: PIIEnforcement; // How should PII be enforced?
+}
+export type SchemaShape = Record<string, FieldBuilder<any>>;
+
+export interface FieldDefinition<T = unknown> {
+  type: FieldType;
+  __valueType?: T;
+  optional?: boolean;
+  immutable?: boolean;
+  description?: string;
+  refType?: string;
+  version?: string;
+  deprecated?: boolean;
+  deprecatedVersion?: string;
+  system?: boolean;
+  autoValidate?: boolean;
+  refPolicy?: "eager" | "lazy";
+  enum?: string[];
+  _shape?: SchemaShape;
+  pii?: PII;
+  validator?: (value: any) => boolean;
+}
+
+export interface ValidateCompositionOptions {
+  resolveEntity: (type: string, id: string) => Promise<any | null>;
+  validatorContext?: { visited: Set<string> };
+  maxDepth?: number;
+  log?: (msg: string) => void; // Optional for trace/debug
+  onlyFields?: string[]; // NEW
+}
+
+export interface Schema<T extends SchemaShape> {
+  //// The shape of the schema.
+  _shape: T;
+
+  //// System metadata about the schema
+  meta: { entityType: string; version: string };
+
+  //// Methods for schema validation
+  schemaValidator: (entity: Infer<T>) => boolean;
+
+  // Validate an input object against the schema
+  validate: (
+    input: unknown,
+    existing?: Record<string, any>
+  ) => ValidationResult<Infer<T>>;
+
+  // Validate an input object against the schema, with options for composition validation
+  validateComposition: (
+    entity: Infer<T>,
+    options: ValidateCompositionOptions
+  ) => Promise<void>;
+
+  //// Optional methods for schema metadata
+
+  // Get the tableName for this schema
+  tableName?: () => string | undefined; // Optional method to get the table name
+
+  //// 🔒 Optional methods for PII handling
+
+  // 🔒 Auto-prepare for read (decrypt PII)
+  prepareForRead(
+    stored: Record<string, any>,
+    decryptFn: (value: string) => any | null
+  ): Record<string, any>;
+
+  // 🔒 Auto-prepare for storage (encrypt/hash PII)
+  prepareForStorage(
+    input: Record<string, any>,
+    encryptFn: (value: any) => string,
+    hashFn: (value: any) => string
+  ): Record<string, any>;
+
+  // 🔒 Sanitize data for logging (e.g., redact PII)
+  sanitizeForLog(
+    data: Record<string, any>,
+    pseudonymFn: (value: any) => string
+  ): Record<string, any>;
+
+  // 🔒 Get PII audit information
+  getPiiAudit(): Array<{
+    field: string;
+    classification: PIIClassification;
+    action: PIIAction;
+    logHandling?: PIILogHandling;
+    purpose?: string;
+  }> | null;
+
+  // 🔒 Scrub PII for deletion (e.g., clear or hash sensitive data)
+  scrubPiiForDelete(stored: Record<string, any>): Record<string, any>;
+
+  describe(): {
+    entityType: string;
+    version: string;
+    shape: Record<
+      string,
+      {
+        type: FieldType;
+        optional: boolean;
+        immutable: boolean;
+        description: string;
+        version: string;
+        deprecated: boolean;
+        deprecatedVersion: string | null;
+        system: boolean;
+        enum: string[] | null;
+        refType: string | null;
+        pii: PII | null;
+      }
+    >;
+  };
+}
+
+export type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object
+    ? T[K] extends (...args: any[]) => any
+      ? T[K]
+      : DeepReadonly<T[K]>
+    : T[K];
+};
+
+export interface ValidationResult<T> {
+  valid: boolean;
+  value?: DeepReadonly<T>;
+  errors?: string[];
+}
+
+export type RefEntityId<T extends string = string> = {
+  type: T;
+  id: string;
+};

package/src/validation/countryCode.ISO3166.ts

@@ -0,0 +1,256 @@
+export const isoCountryCodes = new Set([
+  "AD",
+  "AE",
+  "AF",
+  "AG",
+  "AI",
+  "AL",
+  "AM",
+  "AO",
+  "AQ",
+  "AR",
+  "AS",
+  "AT",
+  "AU",
+  "AW",
+  "AX",
+  "AZ",
+  "BA",
+  "BB",
+  "BD",
+  "BE",
+  "BF",
+  "BG",
+  "BH",
+  "BI",
+  "BJ",
+  "BL",
+  "BM",
+  "BN",
+  "BO",
+  "BQ",
+  "BR",
+  "BS",
+  "BT",
+  "BV",
+  "BW",
+  "BY",
+  "BZ",
+  "CA",
+  "CC",
+  "CD",
+  "CF",
+  "CG",
+  "CH",
+  "CI",
+  "CK",
+  "CL",
+  "CM",
+  "CN",
+  "CO",
+  "CR",
+  "CU",
+  "CV",
+  "CW",
+  "CX",
+  "CY",
+  "CZ",
+  "DE",
+  "DJ",
+  "DK",
+  "DM",
+  "DO",
+  "DZ",
+  "EC",
+  "EE",
+  "EG",
+  "EH",
+  "ER",
+  "ES",
+  "ET",
+  "FI",
+  "FJ",
+  "FM",
+  "FO",
+  "FR",
+  "GA",
+  "GB",
+  "GD",
+  "GE",
+  "GF",
+  "GG",
+  "GH",
+  "GI",
+  "GL",
+  "GM",
+  "GN",
+  "GP",
+  "GQ",
+  "GR",
+  "GT",
+  "GU",
+  "GW",
+  "GY",
+  "HK",
+  "HM",
+  "HN",
+  "HR",
+  "HT",
+  "HU",
+  "ID",
+  "IE",
+  "IL",
+  "IM",
+  "IN",
+  "IO",
+  "IQ",
+  "IR",
+  "IS",
+  "IT",
+  "JE",
+  "JM",
+  "JO",
+  "JP",
+  "KE",
+  "KG",
+  "KH",
+  "KI",
+  "KM",
+  "KN",
+  "KP",
+  "KR",
+  "KW",
+  "KY",
+  "KZ",
+  "LA",
+  "LB",
+  "LC",
+  "LI",
+  "LK",
+  "LR",
+  "LS",
+  "LT",
+  "LU",
+  "LV",
+  "LY",
+  "MA",
+  "MC",
+  "MD",
+  "ME",
+  "MF",
+  "MG",
+  "MH",
+  "MK",
+  "ML",
+  "MM",
+  "MN",
+  "MO",
+  "MP",
+  "MQ",
+  "MR",
+  "MS",
+  "MT",
+  "MU",
+  "MV",
+  "MW",
+  "MX",
+  "MY",
+  "MZ",
+  "NA",
+  "NC",
+  "NE",
+  "NF",
+  "NG",
+  "NI",
+  "NL",
+  "NO",
+  "NP",
+  "NR",
+  "NU",
+  "NZ",
+  "OM",
+  "PA",
+  "PE",
+  "PF",
+  "PG",
+  "PH",
+  "PK",
+  "PL",
+  "PM",
+  "PN",
+  "PR",
+  "PT",
+  "PW",
+  "PY",
+  "QA",
+  "RE",
+  "RO",
+  "RS",
+  "RU",
+  "RW",
+  "SA",
+  "SB",
+  "SC",
+  "SD",
+  "SE",
+  "SG",
+  "SH",
+  "SI",
+  "SJ",
+  "SK",
+  "SL",
+  "SM",
+  "SN",
+  "SO",
+  "SR",
+  "SS",
+  "ST",
+  "SV",
+  "SX",
+  "SY",
+  "SZ",
+  "TC",
+  "TD",
+  "TF",
+  "TG",
+  "TH",
+  "TJ",
+  "TK",
+  "TL",
+  "TM",
+  "TN",
+  "TO",
+  "TR",
+  "TT",
+  "TV",
+  "TZ",
+  "UA",
+  "UG",
+  "UM",
+  "US",
+  "UY",
+  "UZ",
+  "VA",
+  "VC",
+  "VE",
+  "VG",
+  "VI",
+  "VN",
+  "VU",
+  "WF",
+  "WS",
+  "YE",
+  "YT",
+  "ZA",
+  "ZM",
+  "ZW",
+]);
+
+/**
+ * Validates whether a string is a valid ISO 3166-1 alpha-2 country code. 
+ * Performs a case-insensitive lookup against a predefined set of known codes.
+ */
+export const validateCountryCode = (value: unknown): boolean => {
+  if (typeof value !== "string") return false;
+  return isoCountryCodes.has(value.toUpperCase());
+};

package/src/validation/currencyCode.ISO4217.ts

@@ -0,0 +1,191 @@
+export const isoCurrencyCodes = new Set([
+  "AED",
+  "AFN",
+  "ALL",
+  "AMD",
+  "ANG",
+  "AOA",
+  "ARS",
+  "AUD",
+  "AWG",
+  "AZN",
+  "BAM",
+  "BBD",
+  "BDT",
+  "BGN",
+  "BHD",
+  "BIF",
+  "BMD",
+  "BND",
+  "BOB",
+  "BOV",
+  "BRL",
+  "BSD",
+  "BTN",
+  "BWP",
+  "BYN",
+  "BZD",
+  "CAD",
+  "CDF",
+  "CHE",
+  "CHF",
+  "CHW",
+  "CLF",
+  "CLP",
+  "CNY",
+  "COP",
+  "COU",
+  "CRC",
+  "CUC",
+  "CUP",
+  "CVE",
+  "CZK",
+  "DJF",
+  "DKK",
+  "DOP",
+  "DZD",
+  "EGP",
+  "ERN",
+  "ETB",
+  "EUR",
+  "FJD",
+  "FKP",
+  "GBP",
+  "GEL",
+  "GHS",
+  "GIP",
+  "GMD",
+  "GNF",
+  "GTQ",
+  "GYD",
+  "HKD",
+  "HNL",
+  "HRK",
+  "HTG",
+  "HUF",
+  "IDR",
+  "ILS",
+  "INR",
+  "IQD",
+  "IRR",
+  "ISK",
+  "JMD",
+  "JOD",
+  "JPY",
+  "KES",
+  "KGS",
+  "KHR",
+  "KMF",
+  "KPW",
+  "KRW",
+  "KWD",
+  "KYD",
+  "KZT",
+  "LAK",
+  "LBP",
+  "LKR",
+  "LRD",
+  "LSL",
+  "LYD",
+  "MAD",
+  "MDL",
+  "MGA",
+  "MKD",
+  "MMK",
+  "MNT",
+  "MOP",
+  "MRU",
+  "MUR",
+  "MVR",
+  "MWK",
+  "MXN",
+  "MXV",
+  "MYR",
+  "MZN",
+  "NAD",
+  "NGN",
+  "NIO",
+  "NOK",
+  "NPR",
+  "NZD",
+  "OMR",
+  "PAB",
+  "PEN",
+  "PGK",
+  "PHP",
+  "PKR",
+  "PLN",
+  "PYG",
+  "QAR",
+  "RON",
+  "RSD",
+  "RUB",
+  "RWF",
+  "SAR",
+  "SBD",
+  "SCR",
+  "SDG",
+  "SEK",
+  "SGD",
+  "SHP",
+  "SLL",
+  "SOS",
+  "SRD",
+  "SSP",
+  "STN",
+  "SVC",
+  "SYP",
+  "SZL",
+  "THB",
+  "TJS",
+  "TMT",
+  "TND",
+  "TOP",
+  "TRY",
+  "TTD",
+  "TWD",
+  "TZS",
+  "UAH",
+  "UGX",
+  "USD",
+  "USN",
+  "UYI",
+  "UYU",
+  "UYW",
+  "UZS",
+  "VES",
+  "VND",
+  "VUV",
+  "WST",
+  "XAF",
+  "XAG",
+  "XAU",
+  "XBA",
+  "XBB",
+  "XBC",
+  "XBD",
+  "XCD",
+  "XDR",
+  "XOF",
+  "XPD",
+  "XPF",
+  "XPT",
+  "XSU",
+  "XTS",
+  "XUA",
+  "XXX",
+  "YER",
+  "ZAR",
+  "ZMW",
+  "ZWL",
+]);
+
+
+/** 
+ * Validates whether a string is a valid ISO 4217 currency code. 
+ * Performs a case-insensitive lookup against a predefined set of known codes.
+ */
+export const validateCurrencyCode = (value: unknown): boolean => {
+  if (typeof value !== "string") return false;
+  return isoCurrencyCodes.has(value.toUpperCase());
+};

package/src/validation/dateTime.ISO8601.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export const validateDateTimeISO = (value: unknown): boolean => {
+  if (typeof value !== "string") return false;
+  const date = new Date(value);
+  return !isNaN(date.getTime()) && value === date.toISOString();
+};

package/src/validation/email.RFC5322.ts

@@ -0,0 +1,9 @@
+/**
+ * Validates an email string using a simplified RFC 5322-compliant regex.
+ * Returns true if the input is a string in the format `name@domain.tld`.
+ */
+export const validateEmail = (value: unknown): boolean => {
+  if (typeof value !== "string") return false;
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(value);
+};

package/src/validation/generalText.OWASP.ts

@@ -0,0 +1,39 @@
+/**
+ * Validates that a text field is safe for storage (per OWASP guidelines).
+ * Applies to general text fields: names, descriptions, titles, etc.
+ * Global Standard: OWASP Input Validation Cheat Sheet (2024)
+ */
+export function validateSafeText(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+
+  // Trimmed version should not be empty
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+
+  // Reject control chars
+  for (let i = 0; i < trimmed.length; i++) {
+    const code = trimmed.codePointAt(i);
+    if (code !== undefined && (code >= 0x00 && code <= 0x1F || code === 0x7F)) {
+      return false;
+    }
+  }
+
+  // Reject dangerous characters
+  if (/['"<>\\{}();]/.test(trimmed)) return false;
+
+  // Reject SQL-style injection patterns
+  if (
+    /(--|\b(SELECT|UPDATE|DELETE|INSERT|DROP|ALTER|EXEC|UNION|GRANT|REVOKE)\b|\/\*|\*\/|@@)/i.test(
+      trimmed
+    )
+  )
+    return false;
+
+  // Reject null char
+  if (trimmed.includes("\u0000")) return false;
+
+  // Optional: limit length
+  if (trimmed.length > 1024) return false;
+
+  return true;
+}

package/src/validation/index.ts

@@ -0,0 +1,13 @@
+export * from "./email.RFC5322.js";
+export * from "./phone.E.164.js";
+export * from "./url.WHATWG.js";
+export * from "./uuid.RFC4122.js";
+export * from "./dateTime.ISO8601.js";
+export * from "./countryCode.ISO3166.js";
+export * from "./currencyCode.ISO4217.js";
+export * from "./generalText.OWASP.js";
+export * from "./version.SEMVER2.0.0.js";
+export * from "./percentage.ISO80000-1.js";
+export * from "./richtext.OWASP.js";
+export * from "./name.OWASP.js";
+export * from "./user.MS-GOOGLE-APPLE.js";

package/src/validation/name.OWASP.ts

@@ -0,0 +1,25 @@
+/**
+ * Validates that a name is safe, culturally inclusive, and matches global best practice.
+ * Global Standard: OWASP Input Validation Cheat Sheet + ICAO Doc 9303 + IETF PRECIS
+ */
+export function validateName(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+
+  // Limit length (ISO guidance: max 256 is typical)
+  if (trimmed.length > 256) return false;
+
+  // Reject ASCII control chars (U+0000–U+001F and U+007F)
+  for (const ch of trimmed) {
+    const cp = ch.codePointAt(0)!;
+    if ((cp >= 0x00 && cp <= 0x1F) || cp === 0x7F) return false;
+  }
+
+  // Core pattern
+  const namePattern = /^[\p{L}\p{M}'\- ]+$/u;
+  if (!namePattern.test(trimmed)) return false;
+
+  return true;
+}

package/src/validation/percentage.ISO80000-1.ts

@@ -0,0 +1,8 @@
+/**
+ * Validates that a number is a percentage value (0 to 100 inclusive).
+ * Global Standard: ISO 80000-1 percentage definition.
+ */
+export function validatePercentage(value: unknown): boolean {
+  if (typeof value !== "number") return false;
+  return value >= 0 && value <= 100;
+}