@plasius/schema 1.2.5 → 1.2.6

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

@@ -86,6 +86,7 @@ var FieldBuilder = class _FieldBuilder {
     logHandling: "plain",
     purpose: "an ordinary value"
   };
+  _exposure = "public";
   enumValues;
   immutable() {
     this.isImmutable = true;
@@ -95,6 +96,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;
@@ -229,6 +240,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 +1444,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));
@@ -2203,6 +2303,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 +2391,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 +2422,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
     }))
   };
 }