@plasius/schema 1.0.18 → 1.1.1

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:5e59b78b-f6f8-47c0-8329-d6447041544f",
-  "version": 1,
-  "metadata": {
-    "timestamp": "2025-09-17T16:14:58.925Z",
-    "lifecycles": [
-      {
-        "phase": "build"
-      }
-    ],
-    "tools": [
-      {
-        "vendor": "npm",
-        "name": "cli",
-        "version": "10.9.3"
-      }
-    ],
-    "component": {
-      "bom-ref": "@plasius/schema@1.0.18",
-      "type": "library",
-      "name": "schema",
-      "version": "1.0.18",
-      "scope": "required",
-      "author": "Plasius LTD",
-      "description": "Entity schema definition & validation helpers for Plasius ecosystem",
-      "purl": "pkg:npm/%40plasius/schema@1.0.18",
-      "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.0.18",
-      "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,119 +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";
-  _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

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

@@ -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>;

package/src/pii.ts

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