@plasius/schema 1.0.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@plasius/schema",
+  "version": "1.0.0",
+  "description": "Entity schema definition & validation helpers for Plasius ecosystem",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "prepare": "npm run build",
+    "clean": "rimraf dist"
+  },
+  "keywords": [],
+  "author": "Plasius LTD <development@plasius.co.uk>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Plasius-LTD/schema.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Plasius-LTD/schema/issues"
+  },
+  "homepage": "https://github.com/Plasius-LTD/schema#readme",
+  "devDependencies": {
+    "@types/node": "^24.3.1",
+    "@typescript-eslint/eslint-plugin": "^8.43.0",
+    "@typescript-eslint/parser": "^8.43.0",
+    "eslint": "^9.35.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components.ts

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1,119 @@
+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";
+  _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;
+  }
+
+  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;
+  }
+
+  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;
+  }
+
+  as<U>(): FieldBuilder<U, TInternal> {
+    const clone = new FieldBuilder<U, TInternal>(this.type, {
+      shape: this._shape,
+      itemType: this.itemType,
+    });
+    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;
+    return clone;
+  }
+}
+
+export default FieldBuilder;

package/src/field.ts

@@ -0,0 +1,14 @@
+import { FieldBuilder } from "./field.builder.js";
+import { Infer } from "./infer.js";
+import { SchemaShape } from "./types.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 }),
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,34 @@
+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>;

package/src/pii.ts

@@ -0,0 +1,165 @@
+export type PIIClassification = "none" | "low" | "high";
+
+export type PIIAction = "encrypt" | "hash" | "clear" | "none";
+
+export type PIILogHandling = "redact" | "omit" | "pseudonym" | "plain";
+
+export type PiiEnforcement = "strict" | "warn" | "none";
+
+export interface PII {
+  classification: PIIClassification;
+  action: PIIAction;
+  logHandling?: PIILogHandling; // How should this PII be handled in logs?
+  purpose?: string; // optional, for audit: e.g. "user contact", "analytics"
+}
+
+/**
+ * Centralized PII enforcement for field-level validation.
+ * Returns { shortCircuit: true } when in strict mode and value is missing for high PII.
+ */
+export function enforcePIIField(
+  parentKey: string,
+  key: string,
+  value: any,
+  def: any,
+  enforcement: PiiEnforcement = "none",
+  errors?: string[],
+  logger?: { warn: (msg: string) => void }
+): { shortCircuit: boolean } {
+  const path = parentKey ? `${parentKey}.${key}` : key;
+  if (def?._pii?.classification === "high" && (def?.isRequired ?? true)) {
+    const missing = value === undefined || value === null || value === "";
+    if (missing) {
+      const msg = `High PII field must not be empty: ${path}`;
+      if (enforcement === "strict") {
+        errors?.push(msg);
+        return { shortCircuit: true };
+      }
+      if (enforcement === "warn") {
+        logger?.warn?.(`WARN (PII Enforcement): ${msg}`);
+      }
+    }
+  }
+  return { shortCircuit: false };
+}
+
+/**
+ * Apply storage-time PII transforms based on field definitions in shape.
+ */
+export function prepareForStorage(
+  shape: Record<string, any>,
+  input: Record<string, any>,
+  encryptFn: (value: any) => string,
+  hashFn: (value: any) => string
+): Record<string, any> {
+  const result: any = {};
+  for (const key in shape) {
+    const def = shape[key];
+    if (!def) continue;
+    const value = input[key];
+    if (def._pii?.action === "encrypt") {
+      result[key + "Encrypted"] = encryptFn(value);
+    } else if (def._pii?.action === "hash") {
+      result[key + "Hash"] = hashFn(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Apply read-time PII transforms (e.g., decrypt) based on field definitions in shape.
+ */
+export function prepareForRead(
+  shape: Record<string, any>,
+  stored: Record<string, any>,
+  decryptFn: (value: string) => any
+): Record<string, any> {
+  const result: any = {};
+  for (const key in shape) {
+    const def = shape[key];
+    if (!def) continue;
+    if (def._pii?.action === "encrypt") {
+      result[key] = decryptFn(stored[key + "Encrypted"]);
+    } else {
+      result[key] = stored[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Sanitize data for logging according to PII logHandling.
+ */
+export function sanitizeForLog(
+  shape: Record<string, any>,
+  data: Record<string, any>,
+  pseudonymFn: (value: any) => string
+): Record<string, any> {
+  const output: any = {};
+  for (const key in shape) {
+    const def = shape[key];
+    if (!def) continue;
+    const value = data[key];
+    const handling = def._pii?.logHandling as PIILogHandling | undefined;
+    if (handling === "omit") continue;
+    if (handling === "redact") {
+      output[key] = "[REDACTED]";
+    } else if (handling === "pseudonym") {
+      output[key] = pseudonymFn(value);
+    } else {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+
+/**
+ * Produce a PII audit list for the given shape.
+ */
+export function getPiiAudit(shape: Record<string, any>): Array<{
+  field: string;
+  classification: PIIClassification;
+  action: PIIAction;
+  logHandling?: PIILogHandling;
+  purpose?: string;
+}> {
+  const piiFields: Array<any> = [];
+  for (const key in shape) {
+    const def = shape[key];
+    if (!def) continue;
+    if (def._pii && def._pii.classification !== "none") {
+      piiFields.push({
+        field: key,
+        classification: def._pii.classification,
+        action: def._pii.action,
+        logHandling: def._pii.logHandling,
+        purpose: def._pii.purpose,
+      });
+    }
+  }
+  return piiFields;
+}
+
+/**
+ * Scrub PII fields for delete/retention workflows.
+ */
+export function scrubPiiForDelete(
+  shape: Record<string, any>,
+  stored: Record<string, any>
+): Record<string, any> {
+  const result: any = { ...stored };
+  for (const key in shape) {
+    const def = shape[key];
+    if (!def) continue;
+    if (def._pii?.action === "encrypt") {
+      result[key + "Encrypted"] = null;
+    } else if (def._pii?.action === "hash") {
+      result[key + "Hash"] = null;
+    } else if (def._pii?.action === "clear") {
+      result[key] = null;
+    }
+  }
+  return result;
+}