From b0f3387368ef13422e2aa3b35b28b138e994c09b Mon Sep 17 00:00:00 2001
From: FTWinston <ftwinston@gmail.com>
Date: Sat, 3 Oct 2026 00:56:30 +0100
Subject: [PATCH 1/2] MapSchema snapshots are now partial

---
 src/schema/createSnapshot.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/schema/createSnapshot.ts b/src/schema/createSnapshot.ts
index 5265e84..ad853b2 100644
--- a/src/schema/createSnapshot.ts
+++ b/src/schema/createSnapshot.ts
@@ -100,7 +100,7 @@ export type Snapshot<T> = DeepReadonly<
     : T extends IArray<infer U>
     ? Snapshot<U>[]
     : T extends IMap<infer K extends MapKey, infer U>
-    ? Record<K, Snapshot<U>>
+    ? Partial<Record<K, Snapshot<U>>>
     : T extends Primitive
     ? T
     : T extends object
@@ -172,11 +172,11 @@ export function getRefId(node: object): number {
  */
 function createSnapshotForMapSchema(
     node: MapSchema<any>,
-    previousResult: Record<string, any> | undefined,
+    previousResult: Partial<Record<string, any>> | undefined,
     ctx: SnapshotContext,
     isDerived: boolean
-): Record<string, any> {
-    const snapshotted: Record<string, any> = {};
+): Partial<Record<string, any>> {
+    const snapshotted: Partial<Record<string, any>> = {};
     let hasChanged = previousResult === undefined;
 
     for (const [key, value] of node) {

From f1d2510be1fd2c35090eaa026ee37135f9313bd6 Mon Sep 17 00:00:00 2001
From: Endel Dreyer <endel.dreyer@gmail.com>
Date: Fri, 2 Oct 2026 23:24:48 -0300
Subject: [PATCH 2/2] Snapshot: make map entries optional only for finite key
 unions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Partial on every map typed Object.values() entries as possibly undefined,
and MapSchema snapshots skipped the IMap branch entirely. Wide keys keep
the index signature; only literal unions, where Record demanded every
key, become optional — for MapSchema<V, K> and IMap alike.

Assisted-by: Claude Opus 5.5
---
 src/schema/createSnapshot.ts   | 26 +++++++++++++++++++-------
 src/tests/snapshotType.test.ts | 11 +++++++++++
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/src/schema/createSnapshot.ts b/src/schema/createSnapshot.ts
index ad853b2..3233223 100644
--- a/src/schema/createSnapshot.ts
+++ b/src/schema/createSnapshot.ts
@@ -76,11 +76,23 @@ type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 /** Anything usable as a Map key. (MapSchema keys are always strings.) */
 type MapKey = string | number | symbol;
 
+/**
+ * Plain-object form of a map snapshot. Wide keys (`string`, `` `p_${string}` ``)
+ * stay an index signature, so `Object.values()` yields defined entries. A finite
+ * key union (`"red" | "blue"`) becomes optional properties, since a map need not
+ * hold every key. The test: an empty object only satisfies a `Record` with no
+ * required keys.
+ */
+type MapSnapshot<K extends MapKey, V> = Record<never, never> extends Record<K, unknown>
+    ? Record<K, Snapshot<V>>
+    : Partial<Record<K, Snapshot<V>>>;
+
 /**
  * Transforms a Colyseus Schema type into an immutable, plain JavaScript type.
  *
  * - `ArraySchema<T>` (or `Array<T>` / `ReadonlyArray<T>`) becomes `readonly T[]`
- * - `MapSchema<T>` (or `Map<K, T>` / `ReadonlyMap<K, T>`) becomes `Readonly<Record<K, T>>`
+ * - `MapSchema<T, K>` (or `Map<K, T>` / `ReadonlyMap<K, T>`) becomes `Readonly<Record<K, T>>`,
+ *   with every key optional when `K` is a finite union (see `MapSnapshot`)
  * - `Schema` subclasses (and plain objects) become plain objects with only data properties
  * - Primitives remain unchanged
  *
@@ -95,12 +107,12 @@ type MapKey = string | number | symbol;
 export type Snapshot<T> = DeepReadonly<
     T extends ArraySchema<infer U>
     ? Snapshot<U>[]
-    : T extends MapSchema<infer U>
-    ? Record<string, Snapshot<U>>
+    : T extends MapSchema<infer U, infer K>
+    ? MapSnapshot<K, U>
     : T extends IArray<infer U>
     ? Snapshot<U>[]
     : T extends IMap<infer K extends MapKey, infer U>
-    ? Partial<Record<K, Snapshot<U>>>
+    ? MapSnapshot<K, U>
     : T extends Primitive
     ? T
     : T extends object
@@ -172,11 +184,11 @@ export function getRefId(node: object): number {
  */
 function createSnapshotForMapSchema(
     node: MapSchema<any>,
-    previousResult: Partial<Record<string, any>> | undefined,
+    previousResult: Record<string, any> | undefined,
     ctx: SnapshotContext,
     isDerived: boolean
-): Partial<Record<string, any>> {
-    const snapshotted: Partial<Record<string, any>> = {};
+): Record<string, any> {
+    const snapshotted: Record<string, any> = {};
     let hasChanged = previousResult === undefined;
 
     for (const [key, value] of node) {
diff --git a/src/tests/snapshotType.test.ts b/src/tests/snapshotType.test.ts
index 837961c..792bd70 100644
--- a/src/tests/snapshotType.test.ts
+++ b/src/tests/snapshotType.test.ts
@@ -44,6 +44,17 @@ expectMutual<Snapshot<PlayerState>["weapons"], { readonly [k: string]: W }>(true
 expectMutual<Snapshot<IPlayer>["loadout"], ReadonlyArray<W>>(true);
 expectMutual<Snapshot<IPlayer>["weapons"], { readonly [k: string]: W }>(true);
 
+// Finite key unions — a map need not hold every key, so entries are optional.
+type Slot = "primary" | "secondary";
+type SlotW = { readonly primary?: W; readonly secondary?: W };
+expectMutual<Snapshot<MapSchema<Weapon, Slot>>, SlotW>(true);
+expectMutual<Snapshot<ReadonlyMap<Slot, IWeapon>>, SlotW>(true);
+
+// Wide keys stay an index signature, so iterated entries are never `undefined`.
+expectMutual<Snapshot<ReadonlyMap<`p_${string}`, IWeapon>>, { readonly [k: `p_${string}`]: W }>(true);
+const values: W[] = Object.values({} as Snapshot<IPlayer>["weapons"]);
+void values;
+
 // Primitives pass through.
 expectMutual<Snapshot<number>, number>(true);
 expectMutual<Snapshot<string>, string>(true);