@fgv/ts-json-base 5.0.0-29 → 5.0.0-30

package/dist/ts-json-base.d.ts

@@ -209,11 +209,44 @@ declare const jsonArray_2: Validator<JsonArray, IJsonValidatorContext>;
 
 /**
  * A constrained type that is compatible with JSON serialization.
+ *
+ * This type transforms input types to ensure they can be safely serialized to JSON:
+ * - JSON primitives (string, number, boolean, null) are preserved as-is
+ * - `undefined` is allowed for TypeScript compatibility with optional properties
+ * - Objects are recursively transformed with all properties made JSON-compatible
+ * - Arrays are transformed to contain only JSON-compatible elements
+ * - Functions are transformed to error types
+ * - Other non-JSON types are transformed to error types
+ *
+ * Note: While `undefined` is technically not JSON-serializable, it's allowed here
+ * to support TypeScript's optional property patterns. Use `sanitizeJsonObject`
+ * to remove undefined properties before actual JSON serialization.
+ *
  * @param T - The type to be constrained
  * @returns A constrained type that is compatible with JSON serialization.
+ *
+ * @example
+ * ```typescript
+ * interface IUser {
+ *   name: string;
+ *   email?: string; // Optional property can be undefined
+ * }
+ *
+ * type UserCompatible = JsonCompatible<IUser>; // Allows undefined for email
+ *
+ * const user: UserCompatible = {
+ *   name: "John",
+ *   email: undefined // This works
+ * };
+ *
+ * // Before JSON serialization, sanitize to remove undefined:
+ * const sanitized = sanitizeJsonObject(user); // Removes undefined properties
+ * JSON.stringify(sanitized.value); // Safe to serialize
+ * ```
+ *
  * @public
  */
-export declare type JsonCompatible<T> = IsUnknown<T> extends true ? JsonValue : T extends JsonPrimitive ? T : T extends Array<unknown> ? JsonCompatibleArray<T[number]> : T extends Function ? ['Error: Function is not JSON-compatible'] : T extends object ? {
+export declare type JsonCompatible<T> = IsUnknown<T> extends true ? JsonValue : T extends JsonPrimitive | undefined ? T : T extends Array<unknown> ? JsonCompatibleArray<T[number]> : T extends Function ? ['Error: Function is not JSON-compatible'] : T extends object ? {
     [K in keyof T]: JsonCompatible<T[K]>;
 } : ['Error: Non-JSON type'];
 

package/lib/packlets/json/common.d.ts

@@ -35,11 +35,44 @@ export type JsonValueType = 'primitive' | 'object' | 'array';
 type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
 /**
  * A constrained type that is compatible with JSON serialization.
+ *
+ * This type transforms input types to ensure they can be safely serialized to JSON:
+ * - JSON primitives (string, number, boolean, null) are preserved as-is
+ * - `undefined` is allowed for TypeScript compatibility with optional properties
+ * - Objects are recursively transformed with all properties made JSON-compatible
+ * - Arrays are transformed to contain only JSON-compatible elements
+ * - Functions are transformed to error types
+ * - Other non-JSON types are transformed to error types
+ *
+ * Note: While `undefined` is technically not JSON-serializable, it's allowed here
+ * to support TypeScript's optional property patterns. Use `sanitizeJsonObject`
+ * to remove undefined properties before actual JSON serialization.
+ *
  * @param T - The type to be constrained
  * @returns A constrained type that is compatible with JSON serialization.
+ *
+ * @example
+ * ```typescript
+ * interface IUser {
+ *   name: string;
+ *   email?: string; // Optional property can be undefined
+ * }
+ *
+ * type UserCompatible = JsonCompatible<IUser>; // Allows undefined for email
+ *
+ * const user: UserCompatible = {
+ *   name: "John",
+ *   email: undefined // This works
+ * };
+ *
+ * // Before JSON serialization, sanitize to remove undefined:
+ * const sanitized = sanitizeJsonObject(user); // Removes undefined properties
+ * JSON.stringify(sanitized.value); // Safe to serialize
+ * ```
+ *
  * @public
  */
-export type JsonCompatible<T> = IsUnknown<T> extends true ? JsonValue : T extends JsonPrimitive ? T : T extends Array<unknown> ? JsonCompatibleArray<T[number]> : T extends Function ? ['Error: Function is not JSON-compatible'] : T extends object ? {
+export type JsonCompatible<T> = IsUnknown<T> extends true ? JsonValue : T extends JsonPrimitive | undefined ? T : T extends Array<unknown> ? JsonCompatibleArray<T[number]> : T extends Function ? ['Error: Function is not JSON-compatible'] : T extends object ? {
     [K in keyof T]: JsonCompatible<T[K]>;
 } : ['Error: Non-JSON type'];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
-  "version": "5.0.0-29",
+  "version": "5.0.0-30",
   "description": "Typescript types and basic functions for working with json",
   "main": "lib/index.js",
   "types": "dist/ts-json-base.d.ts",
@@ -39,12 +39,12 @@
     "@rushstack/eslint-patch": "~1.12.0",
     "@rushstack/eslint-config": "4.4.0",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-29",
-    "@fgv/ts-extras": "5.0.0-29",
-    "@fgv/ts-utils-jest": "5.0.0-29"
+    "@fgv/ts-utils": "5.0.0-30",
+    "@fgv/ts-utils-jest": "5.0.0-30",
+    "@fgv/ts-extras": "5.0.0-30"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-29"
+    "@fgv/ts-utils": "5.0.0-30"
   },
   "scripts": {
     "build": "heft test --clean",