@plasius/schema 1.2.5 → 1.2.7

package/README.md

@@ -90,6 +90,7 @@ const UserFields = {
 Common methods (non‑exhaustive): `.required()`, `.optional()`, `.default(v|fn)`, `.description(text)`, and type‑specific helpers like `.email()`, `.uuid()`, `.min()`, `.max()`, `.enum([...])`.
 Defaults are applied during validation when inputs are missing/`undefined`.
 Fields are required by default; call `.optional()` (or provide `.default()`) to allow omission.
+Use `.internal()` or `.exposure("internal")` on fields that the server may validate/store but must not include in client-facing payloads.
 
 ### 2) Create a **versioned** schema (enforces `type` + `version`)
 
@@ -144,6 +145,47 @@ if (result.valid && result.errors.length == 0) {
   - PII strict/warn enforcement runs on nested fields, preventing empty high-PII subfields from slipping through.
   - Validation deep-clones inputs before applying defaults, so caller-provided objects/arrays aren’t mutated and non-JSON-safe values (e.g., `Date`) are preserved.
 
+### 3b) Serialize only client-safe fields
+
+Schema serialization is separate from validation. `serialize()` keeps only schema-known fields and drops fields marked `.internal()` unless explicitly requested.
+
+```ts
+const PersistedUserSchema = createSchema(
+  {
+    id: field.string(),
+    partitionKey: field.string().internal(),
+    email: field.email(),
+    audit: field.object({
+      createdBy: field.string().internal(),
+      createdAt: field.dateTimeISO(),
+    }),
+  },
+  "persisted-user",
+  { version: "1.0.0", piiEnforcement: "strict" }
+);
+
+const publicPayload = PersistedUserSchema.serialize({
+  type: "persisted-user",
+  version: "1.0.0",
+  id: "123",
+  partitionKey: "tenant-a",
+  email: "alice@example.com",
+  audit: {
+    createdBy: "admin-1",
+    createdAt: "2026-03-09T00:00:00.000Z",
+  },
+  _rid: "cosmos-only",
+});
+
+// => {
+//   type: "persisted-user",
+//   version: "1.0.0",
+//   id: "123",
+//   email: "alice@example.com",
+//   audit: { createdAt: "2026-03-09T00:00:00.000Z" }
+// }
+```
+
 ### 4) Version enforcement in action
 
 If either `type` or `version` doesn’t match the schema, validation fails.

package/dist/index.cjs

@@ -60,6 +60,12 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/field.builder.ts
+function mergeValidatorResult(previousResult, nextValid) {
+  if (previousResult !== true) {
+    return previousResult;
+  }
+  return nextValid;
+}
 var FieldBuilder = class _FieldBuilder {
   constructor(type, options = {}) {
     this.type = type;
@@ -86,6 +92,7 @@ var FieldBuilder = class _FieldBuilder {
     logHandling: "plain",
     purpose: "an ordinary value"
   };
+  _exposure = "public";
   enumValues;
   immutable() {
     this.isImmutable = true;
@@ -95,6 +102,16 @@ var FieldBuilder = class _FieldBuilder {
     this.isSystem = true;
     return this;
   }
+  exposure(exposure) {
+    this._exposure = exposure;
+    return this;
+  }
+  internal() {
+    return this.exposure("internal");
+  }
+  public() {
+    return this.exposure("public");
+  }
   required() {
     this.isRequired = true;
     return this;
@@ -144,19 +161,19 @@ var FieldBuilder = class _FieldBuilder {
       const prevValidator = this._validator;
       this._validator = (value) => {
         const valid = typeof value === "number" && value >= min;
-        return prevValidator ? prevValidator(value) && valid : valid;
+        return prevValidator ? mergeValidatorResult(prevValidator(value), valid) : valid;
       };
     } else if (this.type === "string") {
       const prevValidator = this._validator;
       this._validator = (value) => {
         const valid = typeof value === "string" && value.length >= min;
-        return prevValidator ? prevValidator(value) && valid : valid;
+        return prevValidator ? mergeValidatorResult(prevValidator(value), valid) : valid;
       };
     } else if (this.type === "array") {
       const prevValidator = this._validator;
       this._validator = (value) => {
         const valid = Array.isArray(value) && value.length >= min;
-        return prevValidator ? prevValidator(value) && valid : valid;
+        return prevValidator ? mergeValidatorResult(prevValidator(value), valid) : valid;
       };
     } else {
       throw new Error(
@@ -170,19 +187,19 @@ var FieldBuilder = class _FieldBuilder {
       const prevValidator = this._validator;
       this._validator = (value) => {
         const valid = typeof value === "number" && value <= max;
-        return prevValidator ? prevValidator(value) && valid : valid;
+        return prevValidator ? mergeValidatorResult(prevValidator(value), valid) : valid;
       };
     } else if (this.type === "string") {
       const prevValidator = this._validator;
       this._validator = (value) => {
         const valid = typeof value === "string" && value.length <= max;
-        return prevValidator ? prevValidator(value) && valid : valid;
+        return prevValidator ? mergeValidatorResult(prevValidator(value), valid) : valid;
       };
     } else if (this.type === "array") {
       const prevValidator = this._validator;
       this._validator = (value) => {
         const valid = Array.isArray(value) && value.length <= max;
-        return prevValidator ? prevValidator(value) && valid : valid;
+        return prevValidator ? mergeValidatorResult(prevValidator(value), valid) : valid;
       };
     } else {
       throw new Error(
@@ -198,7 +215,7 @@ var FieldBuilder = class _FieldBuilder {
     const prevValidator = this._validator;
     this._validator = (value) => {
       const valid = typeof value === "string" && regex.test(value);
-      return prevValidator ? prevValidator(value) && valid : valid;
+      return prevValidator ? mergeValidatorResult(prevValidator(value), valid) : valid;
     };
     return this;
   }
@@ -229,6 +246,7 @@ var FieldBuilder = class _FieldBuilder {
     clone._description = this._description;
     clone._version = this._version;
     clone._pii = this._pii;
+    clone._exposure = this._exposure;
     clone._validator = this._validator;
     clone._default = this._default;
     clone._upgrade = this._upgrade;
@@ -1432,6 +1450,94 @@ function deepClone(value) {
   };
   return cloneAny(value);
 }
+function shouldIncludeField(def, options) {
+  return options.includeInternal === true || (def?._exposure ?? "public") !== "internal";
+}
+function serializeFieldValue(def, value, options) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (value === null) {
+    return null;
+  }
+  switch (def?.type) {
+    case "string":
+    case "number":
+    case "boolean":
+      return deepClone(value);
+    case "ref": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return deepClone(value);
+      }
+      const shape = getShape(def);
+      if (!shape || Object.keys(shape).length === 0) {
+        return deepClone(value);
+      }
+      const serializedRef = {};
+      if (typeof value.type === "string") {
+        serializedRef.type = value.type;
+      }
+      if (typeof value.id === "string") {
+        serializedRef.id = value.id;
+      }
+      for (const [childKey, childDef] of Object.entries(shape)) {
+        if (!shouldIncludeField(childDef, options)) {
+          continue;
+        }
+        if (!Object.prototype.hasOwnProperty.call(value, childKey)) {
+          continue;
+        }
+        const serializedChild = serializeFieldValue(
+          childDef,
+          value[childKey],
+          options
+        );
+        if (serializedChild !== void 0) {
+          serializedRef[childKey] = serializedChild;
+        }
+      }
+      return serializedRef;
+    }
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return deepClone(value);
+      }
+      const shape = getShape(def);
+      if (!shape || Object.keys(shape).length === 0) {
+        return deepClone(value);
+      }
+      const serializedObject = {};
+      for (const [childKey, childDef] of Object.entries(shape)) {
+        if (!shouldIncludeField(childDef, options)) {
+          continue;
+        }
+        if (!Object.prototype.hasOwnProperty.call(value, childKey)) {
+          continue;
+        }
+        const serializedChild = serializeFieldValue(
+          childDef,
+          value[childKey],
+          options
+        );
+        if (serializedChild !== void 0) {
+          serializedObject[childKey] = serializedChild;
+        }
+      }
+      return serializedObject;
+    }
+    case "array": {
+      if (!Array.isArray(value)) {
+        return deepClone(value);
+      }
+      if (!def.itemType) {
+        return deepClone(value);
+      }
+      return value.map((item) => serializeFieldValue(def.itemType, item, options));
+    }
+    default:
+      return deepClone(value);
+  }
+}
 function cmpSemver(a, b) {
   const pa = a.split(".").map((n) => parseInt(n, 10));
   const pb = b.split(".").map((n) => parseInt(n, 10));
@@ -1508,6 +1614,38 @@ function getValidator(def) {
 function getShape(def) {
   return def?._shape ?? def?.shape ?? void 0;
 }
+function normalizeValidationIssue(path, issue, defaultCode) {
+  if (typeof issue === "string") {
+    return {
+      path,
+      code: defaultCode,
+      message: issue
+    };
+  }
+  return {
+    path: issue.path ?? path,
+    code: issue.code || defaultCode,
+    message: issue.message
+  };
+}
+function normalizeValidatorIssues(path, result, defaultCode) {
+  if (result === true) {
+    return [];
+  }
+  if (result === false) {
+    return [
+      {
+        path,
+        code: defaultCode,
+        message: `Invalid value for field: ${path}`
+      }
+    ];
+  }
+  if (Array.isArray(result)) {
+    return result.map((issue) => normalizeValidationIssue(path, issue, defaultCode));
+  }
+  return [normalizeValidationIssue(path, result, defaultCode)];
+}
 function checkMissingRequired(parentKey, key, value, def, errors) {
   if (value === void 0 || value === null) {
     const path = parentKey ? `${parentKey}.${key}` : key;
@@ -1526,13 +1664,16 @@ function checkImmutable(parentKey, key, value, def, existing, errors) {
   }
   return { immutableViolation: false };
 }
-function runCustomValidator(parentKey, key, value, def, errors) {
+function runCustomValidator(parentKey, key, value, def, errors, issues) {
   const validator = getValidator(def);
   if (validator && value !== void 0 && value !== null) {
-    const valid = validator(value);
-    if (!valid) {
-      const path = parentKey ? `${parentKey}.${key}` : key;
-      errors.push(`Invalid value for field: ${path}`);
+    const path = parentKey ? `${parentKey}.${key}` : key;
+    const normalizedIssues = normalizeValidatorIssues(path, validator(value), "invalid_value");
+    if (normalizedIssues.length > 0) {
+      errors.push(...normalizedIssues.map((issue) => issue.message));
+      if (issues) {
+        issues.push(...normalizedIssues);
+      }
       return { invalid: true };
     }
   }
@@ -1572,7 +1713,7 @@ function validateBooleanField(parentKey, key, value, _def, errors) {
     errors.push(`Field ${path} must be boolean`);
   }
 }
-function validateObjectChildren(parentKey, obj, shape, errors, existing, piiEnforcement, logger) {
+function validateObjectChildren(parentKey, obj, shape, errors, issues, existing, piiEnforcement, logger) {
   for (const [childKey, childDef] of Object.entries(shape)) {
     let childValue = obj[childKey];
     const existingChild = existing && typeof existing === "object" ? existing[childKey] : void 0;
@@ -1613,7 +1754,8 @@ function validateObjectChildren(parentKey, obj, shape, errors, existing, piiEnfo
       childKey,
       childValue,
       childDef,
-      errors
+      errors,
+      issues
     );
     if (invalid) continue;
     validateByType(
@@ -1622,13 +1764,14 @@ function validateObjectChildren(parentKey, obj, shape, errors, existing, piiEnfo
       childValue,
       childDef,
       errors,
+      issues,
       existingChild,
       piiEnforcement,
       logger
     );
   }
 }
-function validateObjectField(parentKey, key, value, def, errors, existing, piiEnforcement, logger) {
+function validateObjectField(parentKey, key, value, def, errors, issues, existing, piiEnforcement, logger) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     errors.push(`Field ${path} must be object`);
@@ -1636,7 +1779,7 @@ function validateObjectField(parentKey, key, value, def, errors, existing, piiEn
   }
   const objShape = getShape(def);
   if (objShape)
-    validateObjectChildren(path, value, objShape, errors, existing, piiEnforcement, logger);
+    validateObjectChildren(path, value, objShape, errors, issues, existing, piiEnforcement, logger);
 }
 function validateArrayOfStrings(parentKey, key, arr, itemDef, errors) {
   const path = parentKey ? `${parentKey}.${key}` : key;
@@ -1695,7 +1838,7 @@ function validateArrayOfBooleans(parentKey, key, arr, _itemDef, errors) {
     });
   }
 }
-function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing, piiEnforcement, logger) {
+function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, issues, existing, piiEnforcement, logger) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   if (!Array.isArray(arr) || !arr.every((v) => typeof v === "object" && v !== null && !Array.isArray(v))) {
     errors.push(`Field ${path} must be object[]`);
@@ -1749,7 +1892,8 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing,
         childKey,
         childValue,
         childDef,
-        errors
+        errors,
+        issues
       );
       if (invalid) continue;
       validateByType(
@@ -1758,6 +1902,7 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing,
         childValue,
         childDef,
         errors,
+        issues,
         existingChild,
         piiEnforcement,
         logger
@@ -1765,7 +1910,7 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing,
     }
   });
 }
-function validateArrayField(parentKey, key, value, def, errors, existing, piiEnforcement, logger) {
+function validateArrayField(parentKey, key, value, def, errors, issues, existing, piiEnforcement, logger) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   if (!Array.isArray(value)) {
     errors.push(`Field ${key} must be an array`);
@@ -1785,6 +1930,7 @@ function validateArrayField(parentKey, key, value, def, errors, existing, piiEnf
       value,
       def.itemType,
       errors,
+      issues,
       existing,
       piiEnforcement,
       logger
@@ -1841,9 +1987,14 @@ function validateArrayField(parentKey, key, value, def, errors, existing, piiEnf
             if (shortCircuit) continue;
             const childValidator = getValidator(childDef);
             if (childValidator && childValue !== void 0 && childValue !== null) {
-              const valid = childValidator(childValue);
-              if (!valid) {
-                errors.push(`Invalid value for field: ${childPath}`);
+              const normalizedIssues = normalizeValidatorIssues(
+                childPath,
+                childValidator(childValue),
+                "invalid_value"
+              );
+              if (normalizedIssues.length > 0) {
+                errors.push(...normalizedIssues.map((issue) => issue.message));
+                issues.push(...normalizedIssues);
                 continue;
               }
             }
@@ -1853,6 +2004,7 @@ function validateArrayField(parentKey, key, value, def, errors, existing, piiEnf
               childValue,
               childDef,
               errors,
+              issues,
               existingChild,
               piiEnforcement,
               logger
@@ -1878,7 +2030,7 @@ function validateRefField(parentKey, key, value, def, errors, _existing, _piiEnf
     );
   }
 }
-function validateByType(parentKey, key, value, def, errors, existing, piiEnforcement, logger) {
+function validateByType(parentKey, key, value, def, errors, issues, existing, piiEnforcement, logger) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   switch (def.type) {
     case "string":
@@ -1894,6 +2046,7 @@ function validateByType(parentKey, key, value, def, errors, existing, piiEnforce
         value,
         def,
         errors,
+        issues,
         existing,
         piiEnforcement,
         logger
@@ -1905,6 +2058,7 @@ function validateByType(parentKey, key, value, def, errors, existing, piiEnforce
         value,
         def,
         errors,
+        issues,
         existing,
         piiEnforcement,
         logger
@@ -1940,6 +2094,7 @@ function createSchema(_shape, entityType, options = {
     // 🔗 Validate input against the schema
     validate(input, existing) {
       const errors = [];
+      const issues = [];
       const result = {};
       const piiMode = options.piiEnforcement ?? "none";
       if (typeof input !== "object" || input === null) {
@@ -2003,16 +2158,19 @@ function createSchema(_shape, entityType, options = {
         if (shortCircuit) continue;
         const validateField = (val) => {
           const localErrors = [];
+          const localIssues = [];
           const { invalid } = runCustomValidator(
             "",
             key,
             val,
             def,
-            localErrors
+            localErrors,
+            localIssues
           );
           if (!invalid) {
-            validateByType("", key, val, def, localErrors, existingField, piiMode, console);
+            validateByType("", key, val, def, localErrors, localIssues, existingField, piiMode, console);
           }
+          issues.push(...localIssues);
           return localErrors;
         };
         let fieldValue = value;
@@ -2053,7 +2211,8 @@ function createSchema(_shape, entityType, options = {
       return {
         valid: errors.length === 0,
         value: result,
-        errors
+        errors,
+        issues
       };
     },
     // specific validator for a schema to allow conditional validation
@@ -2203,6 +2362,25 @@ function createSchema(_shape, entityType, options = {
       }
       return store;
     },
+    serialize(input, options2 = {}) {
+      if (typeof input !== "object" || input === null) {
+        return {};
+      }
+      const serialized = {};
+      for (const [key, def] of Object.entries(schema._shape)) {
+        if (!shouldIncludeField(def, options2)) {
+          continue;
+        }
+        if (!Object.prototype.hasOwnProperty.call(input, key)) {
+          continue;
+        }
+        const value = serializeFieldValue(def, input[key], options2);
+        if (value !== void 0) {
+          serialized[key] = value;
+        }
+      }
+      return serialized;
+    },
     /**
      * Transforms an input object for persistence by applying PII protection
      * according to field annotations (e.g., encryption and hashing).
@@ -2272,7 +2450,8 @@ function createSchema(_shape, entityType, options = {
           deprecatedVersion: def.deprecatedVersion === void 0 ? null : def.deprecatedVersion,
           enum: getEnumValues(def) ?? null,
           refType: def.refType ?? null,
-          pii: !def._pii || def._pii.classification === "none" ? null : def._pii
+          pii: !def._pii || def._pii.classification === "none" ? null : def._pii,
+          exposure: def._exposure ?? "public"
         };
       }
       return {
@@ -2302,7 +2481,8 @@ function renderSchemaDescription(schema) {
       optional: def.optional,
       description: def.description,
       deprecated: def.deprecated,
-      pii: def.pii ? def.pii.classification : void 0
+      pii: def.pii ? def.pii.classification : void 0,
+      exposure: def.exposure
     }))
   };
 }