@plasius/schema 1.2.5 → 1.2.6

package/dist/index.d.cts

@@ -10,6 +10,7 @@ interface PII {
 
 type FieldType$1 = "string" | "number" | "boolean" | "object" | "array" | "ref";
 
+type FieldExposure = "public" | "internal";
 declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     type: FieldType$1;
     _type: TExternal;
@@ -35,6 +36,7 @@ declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     itemType?: FieldBuilder<any>;
     refType?: string;
     _pii: PII;
+    _exposure: FieldExposure;
     enumValues?: readonly TInternal[];
     constructor(type: FieldType$1, options?: {
         shape?: Record<string, FieldBuilder<any>>;
@@ -43,6 +45,9 @@ declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     });
     immutable(): FieldBuilder<TExternal, TInternal>;
     system(): FieldBuilder<TExternal, TInternal>;
+    exposure(exposure: FieldExposure): FieldBuilder<TExternal, TInternal>;
+    internal(): FieldBuilder<TExternal, TInternal>;
+    public(): FieldBuilder<TExternal, TInternal>;
     required(): FieldBuilder<TExternal, TInternal>;
     optional(): FieldBuilder<TExternal, TInternal>;
     validator(fn: (value: TInternal) => boolean): FieldBuilder<TExternal, TInternal>;
@@ -136,6 +141,9 @@ interface SchemaOptions {
     piiEnforcement?: PIIEnforcement;
     schemaUpgrade?: SchemaUpgradeStep[] | SchemaUpgradeFunction | undefined;
 }
+interface SerializeOptions {
+    includeInternal?: boolean;
+}
 type SchemaShape = Record<string, FieldBuilder<any>>;
 interface FieldDefinition<T = unknown> {
     type: FieldType;
@@ -153,6 +161,7 @@ interface FieldDefinition<T = unknown> {
     enum?: string[];
     _shape?: SchemaShape;
     pii?: PII;
+    exposure?: FieldExposure;
     validator?: (value: any) => boolean;
 }
 interface ValidateCompositionOptions {
@@ -182,6 +191,7 @@ interface Schema<T extends SchemaShape> {
     };
     validate: (input: unknown, existing?: Record<string, any>) => ValidationResult<Infer<T>>;
     validateComposition: (entity: Infer<T>, options: ValidateCompositionOptions) => Promise<void>;
+    serialize: (input: Record<string, any>, options?: SerializeOptions) => Record<string, any>;
     tableName?: () => string | undefined;
     prepareForRead(stored: Record<string, any>, decryptFn: (value: string) => any | null): Record<string, any>;
     prepareForStorage(input: Record<string, any>, encryptFn: (value: any) => string, hashFn: (value: any) => string): Record<string, any>;
@@ -209,6 +219,7 @@ interface Schema<T extends SchemaShape> {
             enum: string[] | null;
             refType: string | null;
             pii: PII | null;
+            exposure: FieldExposure;
         }>;
     };
 }
@@ -302,6 +313,7 @@ declare function renderSchemaDescription(schema: Schema<any>): {
         description: string;
         deprecated: boolean;
         pii?: string;
+        exposure: "public" | "internal";
     }>;
 };
 
@@ -624,4 +636,4 @@ declare function isPrivateUseSubtag(value: string): boolean;
  */
 declare function validateLanguage(value: unknown): boolean;
 
-export { type DeepReadonly, FieldBuilder, type FieldDefinition, 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 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 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 };

package/dist/index.d.ts

@@ -10,6 +10,7 @@ interface PII {
 
 type FieldType$1 = "string" | "number" | "boolean" | "object" | "array" | "ref";
 
+type FieldExposure = "public" | "internal";
 declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     type: FieldType$1;
     _type: TExternal;
@@ -35,6 +36,7 @@ declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     itemType?: FieldBuilder<any>;
     refType?: string;
     _pii: PII;
+    _exposure: FieldExposure;
     enumValues?: readonly TInternal[];
     constructor(type: FieldType$1, options?: {
         shape?: Record<string, FieldBuilder<any>>;
@@ -43,6 +45,9 @@ declare class FieldBuilder<TExternal = unknown, TInternal = TExternal> {
     });
     immutable(): FieldBuilder<TExternal, TInternal>;
     system(): FieldBuilder<TExternal, TInternal>;
+    exposure(exposure: FieldExposure): FieldBuilder<TExternal, TInternal>;
+    internal(): FieldBuilder<TExternal, TInternal>;
+    public(): FieldBuilder<TExternal, TInternal>;
     required(): FieldBuilder<TExternal, TInternal>;
     optional(): FieldBuilder<TExternal, TInternal>;
     validator(fn: (value: TInternal) => boolean): FieldBuilder<TExternal, TInternal>;
@@ -136,6 +141,9 @@ interface SchemaOptions {
     piiEnforcement?: PIIEnforcement;
     schemaUpgrade?: SchemaUpgradeStep[] | SchemaUpgradeFunction | undefined;
 }
+interface SerializeOptions {
+    includeInternal?: boolean;
+}
 type SchemaShape = Record<string, FieldBuilder<any>>;
 interface FieldDefinition<T = unknown> {
     type: FieldType;
@@ -153,6 +161,7 @@ interface FieldDefinition<T = unknown> {
     enum?: string[];
     _shape?: SchemaShape;
     pii?: PII;
+    exposure?: FieldExposure;
     validator?: (value: any) => boolean;
 }
 interface ValidateCompositionOptions {
@@ -182,6 +191,7 @@ interface Schema<T extends SchemaShape> {
     };
     validate: (input: unknown, existing?: Record<string, any>) => ValidationResult<Infer<T>>;
     validateComposition: (entity: Infer<T>, options: ValidateCompositionOptions) => Promise<void>;
+    serialize: (input: Record<string, any>, options?: SerializeOptions) => Record<string, any>;
     tableName?: () => string | undefined;
     prepareForRead(stored: Record<string, any>, decryptFn: (value: string) => any | null): Record<string, any>;
     prepareForStorage(input: Record<string, any>, encryptFn: (value: any) => string, hashFn: (value: any) => string): Record<string, any>;
@@ -209,6 +219,7 @@ interface Schema<T extends SchemaShape> {
             enum: string[] | null;
             refType: string | null;
             pii: PII | null;
+            exposure: FieldExposure;
         }>;
     };
 }
@@ -302,6 +313,7 @@ declare function renderSchemaDescription(schema: Schema<any>): {
         description: string;
         deprecated: boolean;
         pii?: string;
+        exposure: "public" | "internal";
     }>;
 };
 
@@ -624,4 +636,4 @@ declare function isPrivateUseSubtag(value: string): boolean;
  */
 declare function validateLanguage(value: unknown): boolean;
 
-export { type DeepReadonly, FieldBuilder, type FieldDefinition, 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 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 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 };

package/dist/index.js

@@ -25,6 +25,7 @@ var FieldBuilder = class _FieldBuilder {
     logHandling: "plain",
     purpose: "an ordinary value"
   };
+  _exposure = "public";
   enumValues;
   immutable() {
     this.isImmutable = true;
@@ -34,6 +35,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;
@@ -168,6 +179,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 +1383,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));
@@ -2142,6 +2242,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 +2330,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 +2361,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
     }))
   };
 }