@fgv/ts-json-base 5.0.0-26 → 5.0.0-27

package/README.md

@@ -32,3 +32,153 @@ type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 interface JsonArray extends Array<JsonValue> { }
 ```
 
+### JsonCompatible Type
+
+The `JsonCompatible<T>` type provides compile-time validation that a type is JSON-serializable, unlike `JsonValue` which requires an index signature. This is particularly useful for strongly-typed interfaces.
+
+#### Basic Usage
+
+```typescript
+import { JsonCompatible } from '@fgv/ts-json-base';
+
+// ✅ JSON-compatible interface
+interface UserData {
+  id: string;
+  name: string;
+  preferences: {
+    theme: 'light' | 'dark';
+    notifications: boolean;
+  };
+}
+
+// ✅ This type remains unchanged because it's fully JSON-compatible
+type ValidatedUserData = JsonCompatible<UserData>;
+
+// ❌ Interface with non-JSON properties
+interface UserWithMethods {
+  id: string;
+  name: string;
+  save(): Promise<void>;  // Functions are not JSON-serializable
+}
+
+// ❌ This type transforms 'save' to an error type
+type InvalidUserData = JsonCompatible<UserWithMethods>;
+// Result: { id: string; name: string; save: ['Error: Function is not JSON-compatible'] }
+```
+
+#### The MapOf Pattern
+
+The most powerful application is using `JsonCompatible<T>` as a constraint with default type parameters:
+
+```typescript
+class MapOf<T, TV extends JsonCompatible<T> = JsonCompatible<T>> extends Map<string, TV> {
+  public override set(key: string, value: TV): this {
+    return super.set(key, value);
+  }
+}
+
+// ✅ Works perfectly with JSON-compatible types
+const userMap = new MapOf<UserData>();
+userMap.set('user1', {
+  id: 'user1',
+  name: 'Alice',
+  preferences: { theme: 'dark', notifications: true }
+});
+
+// ❌ Prevents usage with non-JSON-compatible types
+const badMap = new MapOf<UserWithMethods>();
+// The 'save' method becomes type 'never', making the interface unusable
+```
+
+#### Real-World Examples
+
+**API Response Caching:**
+```typescript
+interface ApiResponse {
+  id: string;
+  data: unknown;
+  timestamp: number;
+  metadata: Record<string, string | number>;
+}
+
+class ApiCache extends MapOf<ApiResponse> {
+  setWithTTL(key: string, response: ApiResponse, ttlMs: number) {
+    this.set(key, response);
+    setTimeout(() => this.delete(key), ttlMs);
+  }
+}
+```
+
+**Configuration Management:**
+```typescript
+interface AppConfig {
+  features: Record<string, boolean>;
+  limits: {
+    maxUsers: number;
+    maxStorage: number;
+  };
+  ui: {
+    theme: 'light' | 'dark';
+    language: string;
+  };
+}
+
+// Ensures config is always serializable for storage/transmission
+const configStore = new MapOf<AppConfig>();
+```
+
+**Data Transfer Objects:**
+```typescript
+// ✅ Perfect for DTOs - no methods, just data
+interface CreateUserRequest {
+  name: string;
+  email: string;
+  preferences?: {
+    newsletter: boolean;
+    theme: string;
+  };
+}
+
+const requestCache = new MapOf<CreateUserRequest>();
+
+// ❌ Domain objects with behavior are rejected
+interface User extends CreateUserRequest {
+  id: string;
+  save(): Promise<void>;
+  validate(): boolean;
+}
+
+// This won't work - methods become 'never'
+// const userStore = new MapOf<User>();
+```
+
+#### Array and Nested Validation
+
+```typescript
+// ✅ Arrays of JSON-compatible types work fine
+interface DataStructure {
+  numbers: number[];
+  objects: Array<{ id: number; name: string }>;
+  matrix: number[][];
+}
+
+const dataMap = new MapOf<DataStructure>();
+
+// ❌ Arrays with functions are detected
+interface WithHandlers {
+  callbacks: Array<() => void>;  // Functions in arrays also become 'never'
+  data: string[];
+}
+
+// The 'callbacks' property becomes Array<['Error: Function is not JSON-compatible']>
+const handlersMap = new MapOf<WithHandlers>();
+```
+
+#### Benefits
+
+1. **Compile-time safety**: Non-serializable types are caught during development
+2. **Clear interfaces**: Makes it obvious which types are meant for serialization
+3. **Architecture enforcement**: Separates data objects from behavior objects
+4. **Runtime protection**: Prevents serialization errors in production
+5. **IDE support**: Full autocomplete and error highlighting
+

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

@@ -153,8 +153,8 @@ export declare function isJsonArray(from: unknown): from is JsonArray;
 /**
  * Test if an `unknown` is potentially a {@link JsonObject | JsonObject}.
  * @param from - The `unknown` to be tested.
- * @returns `true` if the supplied parameter is a non-array, non-special object,
- * `false` otherwise.
+ * @returns `true` if the supplied parameter is a non-array, non-special object
+ * with no symbol keys, `false` otherwise.
  * @public
  */
 export declare function isJsonObject(from: unknown): from is JsonObject;
@@ -202,6 +202,24 @@ declare const jsonArray: Converter<JsonArray, IJsonConverterContext>;
  */
 declare const jsonArray_2: Validator<JsonArray, IJsonValidatorContext>;
 
+/**
+ * A constrained type that is compatible with JSON serialization.
+ * @param T - The type to be constrained
+ * @returns A constrained type that is compatible with JSON serialization.
+ * @public
+ */
+export declare type JsonCompatible<T> = T extends JsonPrimitive ? 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'];
+
+/**
+ * A type that represents an array of JSON-compatible values.
+ * @param T - The type to be constrained
+ * @returns A constrained type that is compatible with JSON serialization.
+ * @public
+ */
+export declare type JsonCompatibleArray<T> = Array<JsonCompatible<T>>;
+
 declare namespace JsonFile {
     export {
         readJsonFileSync,

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.52.11"
+      "packageVersion": "7.52.12"
     }
   ]
 }

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

@@ -29,6 +29,22 @@ export interface JsonArray extends Array<JsonValue> {
  * @public
  */
 export type JsonValueType = 'primitive' | 'object' | 'array';
+/**
+ * A constrained type that is compatible with JSON serialization.
+ * @param T - The type to be constrained
+ * @returns A constrained type that is compatible with JSON serialization.
+ * @public
+ */
+export type JsonCompatible<T> = T extends JsonPrimitive ? 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'];
+/**
+ * A type that represents an array of JSON-compatible values.
+ * @param T - The type to be constrained
+ * @returns A constrained type that is compatible with JSON serialization.
+ * @public
+ */
+export type JsonCompatibleArray<T> = Array<JsonCompatible<T>>;
 /**
  * Test if an `unknown` is a {@link JsonValue | JsonValue}.
  * @param from - The `unknown` to be tested
@@ -40,8 +56,8 @@ export declare function isJsonPrimitive(from: unknown): from is JsonPrimitive;
 /**
  * Test if an `unknown` is potentially a {@link JsonObject | JsonObject}.
  * @param from - The `unknown` to be tested.
- * @returns `true` if the supplied parameter is a non-array, non-special object,
- * `false` otherwise.
+ * @returns `true` if the supplied parameter is a non-array, non-special object
+ * with no symbol keys, `false` otherwise.
  * @public
  */
 export declare function isJsonObject(from: unknown): from is JsonObject;

package/lib/packlets/json/common.js

@@ -43,8 +43,8 @@ function isJsonPrimitive(from) {
 /**
  * Test if an `unknown` is potentially a {@link JsonObject | JsonObject}.
  * @param from - The `unknown` to be tested.
- * @returns `true` if the supplied parameter is a non-array, non-special object,
- * `false` otherwise.
+ * @returns `true` if the supplied parameter is a non-array, non-special object
+ * with no symbol keys, `false` otherwise.
  * @public
  */
 function isJsonObject(from) {
@@ -52,7 +52,11 @@ function isJsonObject(from) {
         from !== null &&
         !Array.isArray(from) &&
         !(from instanceof RegExp) &&
-        !(from instanceof Date));
+        !(from instanceof Date) &&
+        !(from instanceof Map) &&
+        !(from instanceof Set) &&
+        !(from instanceof Error) &&
+        Object.getOwnPropertySymbols(from).length === 0);
 }
 /**
  * Test if an `unknown` is potentially a {@link JsonArray | JsonArray}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
-  "version": "5.0.0-26",
+  "version": "5.0.0-27",
   "description": "Typescript types and basic functions for working with json",
   "main": "lib/index.js",
   "types": "dist/ts-json-base.d.ts",
@@ -31,20 +31,20 @@
     "ts-node": "^10.9.2",
     "typescript": "5.8.3",
     "eslint-plugin-n": "^17.21.3",
-    "@rushstack/heft-node-rig": "2.9.4",
-    "@rushstack/heft": "0.74.3",
-    "@rushstack/heft-jest-plugin": "0.16.12",
+    "@rushstack/heft-node-rig": "2.9.5",
+    "@rushstack/heft": "0.74.4",
+    "@rushstack/heft-jest-plugin": "0.16.13",
     "@types/heft-jest": "1.0.6",
     "@microsoft/api-documenter": "^7.26.31",
     "@rushstack/eslint-patch": "~1.12.0",
     "@rushstack/eslint-config": "4.4.0",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-26",
-    "@fgv/ts-extras": "5.0.0-26",
-    "@fgv/ts-utils-jest": "5.0.0-26"
+    "@fgv/ts-utils-jest": "5.0.0-27",
+    "@fgv/ts-extras": "5.0.0-27",
+    "@fgv/ts-utils": "5.0.0-27"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-26"
+    "@fgv/ts-utils": "5.0.0-27"
   },
   "scripts": {
     "build": "heft test --clean",