@fgv/ts-json-base 5.0.0-3 → 5.0.0-31

package/CHANGELOG.json

@@ -1,24 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
   "entries": [
-    {
-      "version": "5.0.0",
-      "tag": "@fgv/ts-json-base_v5.0.0",
-      "date": "Thu, 17 Jul 2025 00:13:24 GMT",
-      "comments": {
-        "none": [
-          {
-            "comment": "add sanitizeJsonObject"
-          },
-          {
-            "comment": "upgrade dependencies"
-          },
-          {
-            "comment": "bump version"
-          }
-        ]
-      }
-    },
     {
       "version": "4.6.0",
       "tag": "@fgv/ts-json-base_v4.6.0",

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
+