@plasius/schema 1.0.10 → 1.0.13

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
@@ -40,6 +38,11 @@ jobs:
           NEW_VER=$(npm version patch -m "chore: release v%s [skip ci]")
           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"
@@ -49,6 +52,104 @@ jobs:
             echo "flags=--access public" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Update CHANGELOG.md (move Unreleased to new version)
+        env:
+          VERSION: ${{ steps.pkg.outputs.version }}
+          TAG: ${{ steps.pkg.outputs.tag }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          FILE="CHANGELOG.md"
+          if [ ! -f "$FILE" ]; then
+            echo "No CHANGELOG.md found; skipping changelog update."
+            exit 0
+          fi
+
+          DATE=$(date -u +%Y-%m-%d)
+          VERSION_LINE="## [${VERSION}] - ${DATE}"
+
+          # Identify Unreleased block boundaries
+          UNREL_START=$(grep -n '^## \[Unreleased\]' "$FILE" | cut -d: -f1 || true)
+          if [ -z "$UNREL_START" ]; then
+            echo "No '## [Unreleased]' section found; skipping changelog update."
+            exit 0
+          fi
+          NEXT_HDR=$(awk 'NR>'"$UNREL_START"' && /^## \[/{print NR; exit}' "$FILE")
+          if [ -z "$NEXT_HDR" ]; then
+            NEXT_HDR=$(wc -l < "$FILE")
+            NEXT_HDR=$((NEXT_HDR+1))
+          fi
+
+          # Extract sections
+          HEADER=$(sed -n "1,${UNREL_START}p" "$FILE")
+          UNREL_CONTENT=$(sed -n "$((UNREL_START+1)),$((NEXT_HDR-1))p" "$FILE")
+          TAIL=$(sed -n "${NEXT_HDR},\$p" "$FILE")
+
+          # Prepare new Unreleased template (Keep a Changelog style) without tabs/indent issues
+          NEW_UNRELEASED=$(printf '%s\n' \
+            '## [Unreleased]' \
+            '- **Added**' \
+            '  - (placeholder)' \
+            '' \
+            '- **Changed**' \
+            '  - (placeholder)' \
+            '' \
+            '- **Fixed**' \
+            '  - (placeholder)' \
+            '' \
+            '- **Security**' \
+            '  - (placeholder)')
+
+          # Build the new CHANGELOG content
+          TMP_FILE=$(mktemp)
+          {
+            printf "%s\n" "$HEADER"
+            printf "%s\n\n" "$NEW_UNRELEASED"
+            printf "%s\n" "$VERSION_LINE"
+            # If Unreleased was empty, at least add a placeholder so the section isn't blank
+            if [ -z "$(echo "$UNREL_CONTENT" | tr -d '\n' | tr -d '[:space:]')" ]; then
+              printf "### Changed\n- (no notable changes)\n\n"
+            else
+              printf "%s\n" "$UNREL_CONTENT"
+              # Ensure a trailing newline after the inserted section
+              printf "\n"
+            fi
+            printf "%s\n" "$TAIL"
+          } > "$TMP_FILE"
+
+          mv "$TMP_FILE" "$FILE"
+
+          # Update bottom compare links
+          # Update [Unreleased] compare to start at v${VERSION}
+          COMPARE_URL="https://github.com/${GITHUB_REPOSITORY}/compare/v${VERSION}...HEAD"
+          sed -E -i.bak "s|^\[Unreleased\]: .*|[Unreleased]: ${COMPARE_URL}|" "$FILE" || true
+          rm -f "$FILE.bak"
+
+          # Append a link for the new version if not present
+          if ! grep -q "^\[${VERSION}\]:" "$FILE"; then
+            echo "[${VERSION}]: https://github.com/${GITHUB_REPOSITORY}/releases/tag/v${VERSION}" >> "$FILE"
+          fi
+
+          git add "$FILE"
+          git commit -m "docs(changelog): release v${VERSION}"
+          git push
+
+      - 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

@@ -1,5 +1,4 @@
 
-
 # Changelog
 
 All notable changes to this project will be documented in this file.
@@ -9,46 +8,63 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 ---
 
 ## [Unreleased]
-### Added
-- (placeholder) Add new validators, field helpers, or PII utilities here.
+## [Unreleased]
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
 
-### Changed
-- (placeholder)
+## [1.0.13] - 2025-09-16
 
-### Fixed
-- (placeholder)
+- **Added**
+  - (placeholder) Add new validators, field helpers, or PII utilities here.
 
-### Security
-- (placeholder)
+- **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)
+
+- **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.
@@ -59,5 +75,6 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 
 ---
 
-[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
+[Unreleased]: https://github.com/Plasius-LTD/schema/compare/v1.0.13...HEAD
+[1.0.0]: https://github.com/Plasius-LTD/plasius-schema/releases/tag/v1.0.0
+[1.0.13]: https://github.com/Plasius-LTD/schema/releases/tag/v1.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/schema",
-  "version": "1.0.10",
+  "version": "1.0.13",
   "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>