@plasius/schema 1.2.5 → 1.2.7

package/dist/index.js

@@ -1,4 +1,10 @@
 // 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;
@@ -25,6 +31,7 @@ var FieldBuilder = class _FieldBuilder {
     logHandling: "plain",
     purpose: "an ordinary value"
   };
+  _exposure = "public";
   enumValues;
   immutable() {
     this.isImmutable = true;
@@ -34,6 +41,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;
@@ -83,19 +100,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(
@@ -109,19 +126,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(
@@ -137,7 +154,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;
   }
@@ -168,6 +185,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;
@@ -1371,6 +1389,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));
@@ -1447,6 +1553,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;
@@ -1465,13 +1603,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 };
     }
   }
@@ -1511,7 +1652,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;
@@ -1552,7 +1693,8 @@ function validateObjectChildren(parentKey, obj, shape, errors, existing, piiEnfo
       childKey,
       childValue,
       childDef,
-      errors
+      errors,
+      issues
     );
     if (invalid) continue;
     validateByType(
@@ -1561,13 +1703,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`);
@@ -1575,7 +1718,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;
@@ -1634,7 +1777,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[]`);
@@ -1688,7 +1831,8 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing,
         childKey,
         childValue,
         childDef,
-        errors
+        errors,
+        issues
       );
       if (invalid) continue;
       validateByType(
@@ -1697,6 +1841,7 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing,
         childValue,
         childDef,
         errors,
+        issues,
         existingChild,
         piiEnforcement,
         logger
@@ -1704,7 +1849,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`);
@@ -1724,6 +1869,7 @@ function validateArrayField(parentKey, key, value, def, errors, existing, piiEnf
       value,
       def.itemType,
       errors,
+      issues,
       existing,
       piiEnforcement,
       logger
@@ -1780,9 +1926,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;
               }
             }
@@ -1792,6 +1943,7 @@ function validateArrayField(parentKey, key, value, def, errors, existing, piiEnf
               childValue,
               childDef,
               errors,
+              issues,
               existingChild,
               piiEnforcement,
               logger
@@ -1817,7 +1969,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":
@@ -1833,6 +1985,7 @@ function validateByType(parentKey, key, value, def, errors, existing, piiEnforce
         value,
         def,
         errors,
+        issues,
         existing,
         piiEnforcement,
         logger
@@ -1844,6 +1997,7 @@ function validateByType(parentKey, key, value, def, errors, existing, piiEnforce
         value,
         def,
         errors,
+        issues,
         existing,
         piiEnforcement,
         logger
@@ -1879,6 +2033,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) {
@@ -1942,16 +2097,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;
@@ -1992,7 +2150,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
@@ -2142,6 +2301,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).
@@ -2211,7 +2389,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 {
@@ -2241,7 +2420,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
     }))
   };
 }