@plasius/schema 1.0.9 → 1.0.11

package/.github/workflows/cd.yml

@@ -2,8 +2,6 @@ name: CD (Publish to npm)
 
 on:
   workflow_dispatch:
-  release:
-    types: [published]
 
 permissions:
   contents: write
@@ -12,7 +10,7 @@ permissions:
 jobs:
   publish:
     runs-on: ubuntu-latest
-    environment: npm
+    environment: production
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -41,6 +39,11 @@ jobs:
           echo "New version: $NEW_VER"
           git push --follow-tags
 
+          # Expose tag (vX.Y.Z) and version (X.Y.Z) for later steps
+          VER_NO_V=${NEW_VER#v}
+          echo "tag=$NEW_VER" >> "$GITHUB_OUTPUT"
+          echo "version=$VER_NO_V" >> "$GITHUB_OUTPUT"
+
           NAME=$(node -p "require('./package.json').name")
           echo "name=$NAME" >> "$GITHUB_OUTPUT"
           if npm view "$NAME" version >/dev/null 2>&1; then
@@ -49,6 +52,21 @@ jobs:
             echo "flags=--access public" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Create GitHub Release from tag (first-party)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.pkg.outputs.tag }}"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists; skipping creation."
+          else
+            gh release create "$TAG" \
+              --title "Release $TAG" \
+              --generate-notes \
+              --latest
+          fi
+
       - name: Publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.vscode/launch.json

@@ -6,7 +6,7 @@
       "request": "launch",
       "name": "Debug Vitest",
       "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
-      "args": ["run", "--dir", "tests"],
+      "args": ["run"],
       "cwd": "${workspaceFolder}",
       "console": "integratedTerminal",
       "skipFiles": ["<node_internals>/**"]

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)**, and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0.0.html)**.
+
+---
+
+## [Unreleased]
+
+- **Added**
+  - (placeholder) Add new validators, field helpers, or PII utilities here.
+
+- **Changed**
+  - ./src/schema.ts Added comments defining functionality on all externally facing functions.
+
+- **Fixed**
+  - ./src/schema.ts Validation no longer mutates the input, internal system fields are set only on result if not previously present.
+
+- **Security**
+  - (placeholder)
+
+---
+
+## [1.0.0] - 2025-09-16
+
+- **Added**
+  - Initial public release of `@plasius/schema`.
+  - Fluent field builder API: `field().string().required()`, `field().number().min()`, etc.
+  - Type inference utilities to derive TypeScript types from schema definitions.
+  - Built-in validators for common standards:
+    - ISO-3166 country codes
+    - ISO-4217 currency codes
+    - RFC 5322 email format
+    - E.164 phone format
+    - WHATWG URL format
+    - ISO 8601 date/time
+    - OWASP-guided text/name constraints
+    - UUID (RFC 4122) and SemVer 2.0.0
+  - PII annotations and helpers for redaction/masking before logging.
+  - Lightweight validation runner with success/error result types.
+
+- **Changed**
+  - N/A (initial release)
+
+- **Fixed**
+  - N/A (initial release)
+
+---
+
+## Release process (maintainers)
+
+1. Update `CHANGELOG.md` under **Unreleased** with user‑visible changes.
+2. Bump version in `package.json` following SemVer (major/minor/patch).
+3. Move entries from **Unreleased** to a new version section with the current date.
+4. Tag the release in Git (`vX.Y.Z`) and push tags.
+5. Publish to npm (via CI/CD or `npm publish`).
+
+> Tip: Use Conventional Commits in PR titles/bodies to make changelog updates easier.
+
+---
+
+[Unreleased]: https://github.com/Plasius-LTD/plasius-schema/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/Plasius-LTD/plasius-schema/releases/tag/v1.0.0

package/README.md

@@ -48,7 +48,7 @@ This ensures your local development environment matches the version used in CI/C
 We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
 - [Code of Conduct](./CODE_OF_CONDUCT.md)
-- [Contributor License Agreement](./CLA.md)
+- [Contributor License Agreement](./legal/CLA.md)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/schema",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Entity schema definition & validation helpers for Plasius ecosystem",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/schema.ts

@@ -500,15 +500,14 @@ export function createSchema<S extends SchemaShape>(
       if (typeof input !== "object" || input === null) {
         return { valid: false, errors: ["Input must be an object"] } as any;
       }
-
-      if (!(input as any).type || !(input as any).version) {
-        (input as any).type = entityType;
-        (input as any).version = version;
-      }
+      // Work on a non-mutating copy that includes system defaults for first-time objects
+      const working: Record<string, any> = { ...(input as any) };
+      if (working.type == null) working.type = entityType;
+      if (working.version == null) working.version = version;
 
       for (const key in schema._shape) {
         const def = schema._shape[key];
-        const value = (input as any)[key];
+        const value = working[key];
 
         if (!def) {
           errors.push(`Field definition missing for: ${key}`);
@@ -553,6 +552,7 @@ export function createSchema<S extends SchemaShape>(
         result[key] = value;
       }
 
+
       if (errors.length === 0 && options.schemaValidator) {
         const castValue = result as Infer<S>;
         if (!options.schemaValidator(castValue)) {
@@ -570,7 +570,28 @@ export function createSchema<S extends SchemaShape>(
     // specific validator for a schema to allow conditional validation
     schemaValidator: options.schemaValidator!, // <== expose it here!
 
-    // 🔗 Validate composition (references) recursively
+    /**
+     * Recursively validates entity references defined in this schema.
+     *
+     * Traverses fields of type `ref` and arrays of `ref` and resolves each target
+     * entity using the provided `resolveEntity` function. When `autoValidate` is
+     * enabled (default) and the field's `refPolicy` is `eager`, the referenced
+     * entity's schema is fetched and validated via `validateComposition` up to
+     * `maxDepth` levels.
+     *
+     * Skips fields not listed in `onlyFields` when provided. Prevents cycles via
+     * a `visited` set in `validatorContext`.
+     *
+     * @param entity The root entity to validate (must include `type` and `id`).
+     * @param options Options controlling traversal and resolution behavior.
+     * @param options.resolveEntity Function to resolve a referenced entity by type and id.
+     * @param options.validatorContext Internal context (visited set) to prevent cycles.
+     * @param options.maxDepth Maximum depth for recursive validation (default: 5).
+     * @param options.onlyFields Optional whitelist of field names to validate.
+     * @param options.log Optional logger for traversal/debug output.
+     *
+     * @throws Error if a broken reference is encountered (target cannot be resolved).
+     */
     async validateComposition(entity, options) {
       const {
         resolveEntity,
@@ -643,6 +664,11 @@ export function createSchema<S extends SchemaShape>(
       }
     },
 
+    /**
+     * Returns the configured table name for this schema.
+     *
+     * @throws Error if no store/table name has been defined for this schema.
+     */
     tableName(): string {
       if (!store || store === "") {
         throw new Error("Store is not defined for this schema");
@@ -650,7 +676,15 @@ export function createSchema<S extends SchemaShape>(
       return store;
     },
 
-    // 🔒 Auto-prepare for storage (encrypt/hash PII)
+    /**
+     * Transforms an input object for persistence by applying PII protection
+     * according to field annotations (e.g., encryption and hashing).
+     *
+     * @param input The raw entity data.
+     * @param encryptFn Function used to encrypt sensitive values.
+     * @param hashFn Function used to hash sensitive values.
+     * @returns A new object safe to store.
+     */
     prepareForStorage(
       input: Record<string, any>,
       encryptFn: (value: any) => string,
@@ -659,6 +693,14 @@ export function createSchema<S extends SchemaShape>(
       return piiPrepareForStorage(_shape, input, encryptFn, hashFn);
     },
 
+    /**
+     * Reverses storage transformations for read paths (e.g., decrypts values)
+     * according to PII annotations, returning a consumer-friendly object.
+     *
+     * @param stored Data retrieved from storage.
+     * @param decryptFn Function used to decrypt values that were encrypted on write.
+     * @returns A new object suitable for application consumption.
+     */
     prepareForRead(
       stored: Record<string, any>,
       decryptFn: (value: string) => any
@@ -666,7 +708,14 @@ export function createSchema<S extends SchemaShape>(
       return piiPrepareForRead(_shape, stored, decryptFn);
     },
 
-    // 🔍 Sanitize for logging (redact/pseudonymize PII)
+    /**
+     * Produces a log-safe copy of the provided data by redacting or pseudonymizing
+     * PII fields in accordance with field annotations.
+     *
+     * @param data Arbitrary data to sanitize for logging.
+     * @param pseudonymFn Function producing stable pseudonyms for sensitive values.
+     * @returns A copy safe to emit to logs.
+     */
     sanitizeForLog(
       data: Record<string, any>,
       pseudonymFn: (value: any) => string
@@ -674,6 +723,10 @@ export function createSchema<S extends SchemaShape>(
       return piiSanitizeForLog(_shape, data, pseudonymFn);
     },
 
+    /**
+     * Returns a list of fields annotated with PII metadata for auditing purposes.
+     * Each entry includes classification, required action, and optional log policy.
+     */
     getPiiAudit(): Array<{
       field: string;
       classification: PIIClassification;
@@ -684,10 +737,21 @@ export function createSchema<S extends SchemaShape>(
       return piiGetPiiAudit(_shape);
     },
 
+    /**
+     * Produces a copy of stored data suitable for data deletion flows by scrubbing
+     * or blanking PII per field annotations.
+     *
+     * @param stored Data as persisted.
+     * @returns A copy with PII removed or neutralized for deletion.
+     */
     scrubPiiForDelete(stored: Record<string, any>): Record<string, any> {
       return piiScrubPiiForDelete(_shape, stored);
     },
 
+    /**
+     * Returns a normalized description of the schema suitable for documentation
+     * or UI rendering (type, optionality, enum values, PII flags, etc.).
+     */
     describe() {
       const description: Record<string, any> = {};
       for (const [key, def] of Object.entries(schema._shape)) {
@@ -715,19 +779,24 @@ export function createSchema<S extends SchemaShape>(
   return schema;
 }
 
-// 🔗 Retrieve a previously registered schema globally
+/**
+ * Retrieves a previously registered schema by its `entityType` from the
+ * in-process global schema registry.
+ */
 export function getSchemaForType(type: string): Schema<any> | undefined {
   return globalSchemaRegistry.get(type);
 }
 
-// 🔗 Retrieve all registered schemas globally
+/**
+ * Returns all schemas registered in the in-process global registry.
+ */
 export function getAllSchemas(): Schema<any>[] {
   return Array.from(globalSchemaRegistry.values());
 }
 
 /**
- * Renders a schema description to a simplified frontend-consumable format.
- * This can be used in UIs for schema explorers, documentation, or admin tools.
+ * Renders a schema into a simplified descriptor for front-end consumption.
+ * Intended for documentation and admin tooling rather than validation.
  */
 export function renderSchemaDescription(
   schema: Schema<any>