@plasius/schema 1.2.6 → 1.2.8

package/dist/index.d.cts

@@ -8,6 +8,21 @@ interface PII {
     purpose?: string;
 }
 
+interface ValidationIssueInput {
+    code: string;
+    message: string;
+    path?: string;
+}
+interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+type FieldValidatorResult = boolean | string | ValidationIssueInput | ValidationIssueInput[];
+type FieldValidator<T = unknown> = {
+    bivarianceHack(value: T): FieldValidatorResult;
+}["bivarianceHack"];
+
 type FieldType$1 = "string" | "number" | "boolean" | "object" | "array" | "ref";
 
 type FieldExposure = "public" | "internal";
@@ -18,7 +33,7 @@ declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     isSystem: boolean;
     isImmutable: boolean;
     isRequired: boolean;
-    _validator?: (value: any) => boolean;
+    _validator?: FieldValidator<TInternal>;
     _description: string;
     _version: string;
     _default?: TInternal | (() => TInternal);
@@ -50,7 +65,7 @@ declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     public(): FieldBuilder<TExternal, TInternal>;
     required(): FieldBuilder<TExternal, TInternal>;
     optional(): FieldBuilder<TExternal, TInternal>;
-    validator(fn: (value: TInternal) => boolean): FieldBuilder<TExternal, TInternal>;
+    validator(fn: FieldValidator<TInternal>): FieldBuilder<TExternal, TInternal>;
     description(desc: string): FieldBuilder<TExternal, TInternal>;
     default(value: TInternal | (() => TInternal)): FieldBuilder<TExternal, TInternal>;
     /**
@@ -162,7 +177,7 @@ interface FieldDefinition<T = unknown> {
     _shape?: SchemaShape;
     pii?: PII;
     exposure?: FieldExposure;
-    validator?: (value: any) => boolean;
+    validator?: FieldValidator<T>;
 }
 interface ValidateCompositionOptions {
     resolveEntity: (type: string, id: string) => Promise<any | null>;
@@ -230,6 +245,7 @@ interface ValidationResult<T> {
     valid: boolean;
     value?: DeepReadonly<T>;
     errors?: string[];
+    issues?: ValidationIssue[];
 }
 type RefEntityId<T extends string = string> = {
     type: T;
@@ -636,4 +652,4 @@ declare function isPrivateUseSubtag(value: string): boolean;
  */
 declare function validateLanguage(value: unknown): boolean;
 
-export { type DeepReadonly, FieldBuilder, type FieldDefinition, type FieldExposure, type FieldType, type FieldTypeMap, type Infer, IsoLanguageCode, type PIIEnforcement, type RefEntityId, type Schema, type SchemaOptions, type SchemaShape, type SchemaUpgradeFunction, type SchemaUpgradeResult, type SchemaUpgradeSpec, type SchemaUpgradeStep, type SerializeOptions, type ValidateCompositionOptions, type ValidationResult, createComponentSchema, createSchema, field, getAllComponentSchemas, getAllSchemas, getComponentSchema, getSchemaForType, isExtensionSingleton, isExtensionSubtag, isIsoLanguageCode, isPrivateUseSingleton, isPrivateUseSubtag, isRegionSubtag, isScriptSubtag, isVariantSubtag, isoCountryCodes, isoCurrencyCodes, registerComponentSchema, renderSchemaDescription, validateCountryCode, validateCurrencyCode, validateDateTimeISO, validateEmail, validateLanguage, validateName, validatePercentage, validatePhone, validateRichText, validateSafeText, validateSemVer, validateUUID, validateUrl, validateUserId, validateUserIdArray };
+export { type DeepReadonly, FieldBuilder, type FieldDefinition, type FieldExposure, type FieldType, type FieldTypeMap, type FieldValidator, type FieldValidatorResult, type Infer, IsoLanguageCode, type PIIEnforcement, type RefEntityId, type Schema, type SchemaOptions, type SchemaShape, type SchemaUpgradeFunction, type SchemaUpgradeResult, type SchemaUpgradeSpec, type SchemaUpgradeStep, type SerializeOptions, type ValidateCompositionOptions, type ValidationIssue, type ValidationIssueInput, type ValidationResult, createComponentSchema, createSchema, field, getAllComponentSchemas, getAllSchemas, getComponentSchema, getSchemaForType, isExtensionSingleton, isExtensionSubtag, isIsoLanguageCode, isPrivateUseSingleton, isPrivateUseSubtag, isRegionSubtag, isScriptSubtag, isVariantSubtag, isoCountryCodes, isoCurrencyCodes, registerComponentSchema, renderSchemaDescription, validateCountryCode, validateCurrencyCode, validateDateTimeISO, validateEmail, validateLanguage, validateName, validatePercentage, validatePhone, validateRichText, validateSafeText, validateSemVer, validateUUID, validateUrl, validateUserId, validateUserIdArray };

package/dist/index.d.ts

@@ -8,6 +8,21 @@ interface PII {
     purpose?: string;
 }
 
+interface ValidationIssueInput {
+    code: string;
+    message: string;
+    path?: string;
+}
+interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+type FieldValidatorResult = boolean | string | ValidationIssueInput | ValidationIssueInput[];
+type FieldValidator<T = unknown> = {
+    bivarianceHack(value: T): FieldValidatorResult;
+}["bivarianceHack"];
+
 type FieldType$1 = "string" | "number" | "boolean" | "object" | "array" | "ref";
 
 type FieldExposure = "public" | "internal";
@@ -18,7 +33,7 @@ declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     isSystem: boolean;
     isImmutable: boolean;
     isRequired: boolean;
-    _validator?: (value: any) => boolean;
+    _validator?: FieldValidator<TInternal>;
     _description: string;
     _version: string;
     _default?: TInternal | (() => TInternal);
@@ -50,7 +65,7 @@ declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     public(): FieldBuilder<TExternal, TInternal>;
     required(): FieldBuilder<TExternal, TInternal>;
     optional(): FieldBuilder<TExternal, TInternal>;
-    validator(fn: (value: TInternal) => boolean): FieldBuilder<TExternal, TInternal>;
+    validator(fn: FieldValidator<TInternal>): FieldBuilder<TExternal, TInternal>;
     description(desc: string): FieldBuilder<TExternal, TInternal>;
     default(value: TInternal | (() => TInternal)): FieldBuilder<TExternal, TInternal>;
     /**
@@ -162,7 +177,7 @@ interface FieldDefinition<T = unknown> {
     _shape?: SchemaShape;
     pii?: PII;
     exposure?: FieldExposure;
-    validator?: (value: any) => boolean;
+    validator?: FieldValidator<T>;
 }
 interface ValidateCompositionOptions {
     resolveEntity: (type: string, id: string) => Promise<any | null>;
@@ -230,6 +245,7 @@ interface ValidationResult<T> {
     valid: boolean;
     value?: DeepReadonly<T>;
     errors?: string[];
+    issues?: ValidationIssue[];
 }
 type RefEntityId<T extends string = string> = {
     type: T;
@@ -636,4 +652,4 @@ declare function isPrivateUseSubtag(value: string): boolean;
  */
 declare function validateLanguage(value: unknown): boolean;
 
-export { type DeepReadonly, FieldBuilder, type FieldDefinition, type FieldExposure, type FieldType, type FieldTypeMap, type Infer, IsoLanguageCode, type PIIEnforcement, type RefEntityId, type Schema, type SchemaOptions, type SchemaShape, type SchemaUpgradeFunction, type SchemaUpgradeResult, type SchemaUpgradeSpec, type SchemaUpgradeStep, type SerializeOptions, type ValidateCompositionOptions, type ValidationResult, createComponentSchema, createSchema, field, getAllComponentSchemas, getAllSchemas, getComponentSchema, getSchemaForType, isExtensionSingleton, isExtensionSubtag, isIsoLanguageCode, isPrivateUseSingleton, isPrivateUseSubtag, isRegionSubtag, isScriptSubtag, isVariantSubtag, isoCountryCodes, isoCurrencyCodes, registerComponentSchema, renderSchemaDescription, validateCountryCode, validateCurrencyCode, validateDateTimeISO, validateEmail, validateLanguage, validateName, validatePercentage, validatePhone, validateRichText, validateSafeText, validateSemVer, validateUUID, validateUrl, validateUserId, validateUserIdArray };
+export { type DeepReadonly, FieldBuilder, type FieldDefinition, type FieldExposure, type FieldType, type FieldTypeMap, type FieldValidator, type FieldValidatorResult, type Infer, IsoLanguageCode, type PIIEnforcement, type RefEntityId, type Schema, type SchemaOptions, type SchemaShape, type SchemaUpgradeFunction, type SchemaUpgradeResult, type SchemaUpgradeSpec, type SchemaUpgradeStep, type SerializeOptions, type ValidateCompositionOptions, type ValidationIssue, type ValidationIssueInput, type ValidationResult, createComponentSchema, createSchema, field, getAllComponentSchemas, getAllSchemas, getComponentSchema, getSchemaForType, isExtensionSingleton, isExtensionSubtag, isIsoLanguageCode, isPrivateUseSingleton, isPrivateUseSubtag, isRegionSubtag, isScriptSubtag, isVariantSubtag, isoCountryCodes, isoCurrencyCodes, registerComponentSchema, renderSchemaDescription, validateCountryCode, validateCurrencyCode, validateDateTimeISO, validateEmail, validateLanguage, validateName, validatePercentage, validatePhone, validateRichText, validateSafeText, validateSemVer, validateUUID, validateUrl, validateUserId, validateUserIdArray };

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;
@@ -6,6 +12,7 @@ var FieldBuilder = class _FieldBuilder {
     this.itemType = options.itemType;
     this.refType = options.refType;
   }
+  type;
   _type;
   _storageType;
   isSystem = false;
@@ -94,19 +101,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(
@@ -120,19 +127,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(
@@ -148,7 +155,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;
   }
@@ -1547,6 +1554,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;
@@ -1565,13 +1604,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 };
     }
   }
@@ -1611,7 +1653,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;
@@ -1652,7 +1694,8 @@ function validateObjectChildren(parentKey, obj, shape, errors, existing, piiEnfo
       childKey,
       childValue,
       childDef,
-      errors
+      errors,
+      issues
     );
     if (invalid) continue;
     validateByType(
@@ -1661,13 +1704,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`);
@@ -1675,7 +1719,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;
@@ -1734,7 +1778,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[]`);
@@ -1788,7 +1832,8 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing,
         childKey,
         childValue,
         childDef,
-        errors
+        errors,
+        issues
       );
       if (invalid) continue;
       validateByType(
@@ -1797,6 +1842,7 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing,
         childValue,
         childDef,
         errors,
+        issues,
         existingChild,
         piiEnforcement,
         logger
@@ -1804,7 +1850,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`);
@@ -1824,6 +1870,7 @@ function validateArrayField(parentKey, key, value, def, errors, existing, piiEnf
       value,
       def.itemType,
       errors,
+      issues,
       existing,
       piiEnforcement,
       logger
@@ -1880,9 +1927,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;
               }
             }
@@ -1892,6 +1944,7 @@ function validateArrayField(parentKey, key, value, def, errors, existing, piiEnf
               childValue,
               childDef,
               errors,
+              issues,
               existingChild,
               piiEnforcement,
               logger
@@ -1917,7 +1970,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":
@@ -1933,6 +1986,7 @@ function validateByType(parentKey, key, value, def, errors, existing, piiEnforce
         value,
         def,
         errors,
+        issues,
         existing,
         piiEnforcement,
         logger
@@ -1944,6 +1998,7 @@ function validateByType(parentKey, key, value, def, errors, existing, piiEnforce
         value,
         def,
         errors,
+        issues,
         existing,
         piiEnforcement,
         logger
@@ -1979,6 +2034,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) {
@@ -2042,16 +2098,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;
@@ -2092,7 +2151,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