jazz-tools 0.17.14 → 0.18.1

package/src/tools/coValues/coMap.ts

@@ -8,10 +8,12 @@ import {
   type RawCoMap,
   cojsonInternals,
 } from "cojson";
-import type {
+import {
   AnonymousJazzAgent,
+  CoFieldInit,
   CoValue,
   CoValueClass,
+  getCoValueOwner,
   Group,
   ID,
   PartialOnUndefined,
@@ -24,10 +26,12 @@ import type {
   Simplify,
   SubscribeListenerOptions,
   SubscribeRestArgs,
+  TypeSym,
 } from "../internal.js";
 import {
   Account,
   CoValueBase,
+  CoValueJazzApi,
   ItemsSym,
   Ref,
   RegisteredSchemas,
@@ -57,6 +61,14 @@ type CoMapEdit<V> = {
 
 type LastAndAllCoMapEdits<V> = CoMapEdit<V> & { all: CoMapEdit<V>[] };
 
+type CoMapEdits<M extends CoMap> = {
+  [Key in CoKeys<M>]?: LastAndAllCoMapEdits<M[Key]>;
+};
+
+type CoMapFieldSchema = {
+  [key: string]: Schema;
+} & { [ItemsSym]?: Schema };
+
 /**
  * CoMaps are collaborative versions of plain objects, mapping string-like keys to values.
  *
@@ -91,196 +103,44 @@ type LastAndAllCoMapEdits<V> = CoMapEdit<V> & { all: CoMapEdit<V>[] };
  * @category CoValues
  *  */
 export class CoMap extends CoValueBase implements CoValue {
-  /**
-   * The ID of this `CoMap`
-   * @category Content */
-  declare id: ID<this>;
   /** @category Type Helpers */
-  declare _type: "CoMap";
+  declare [TypeSym]: "CoMap";
   static {
-    this.prototype._type = "CoMap";
-  }
-  /** @category Internals */
-  declare _raw: RawCoMap;
-
-  /** @internal */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  static _schema: any;
-  /** @internal */
-  get _schema() {
-    return (this.constructor as typeof CoMap)._schema as {
-      [key: string]: Schema;
-    } & { [ItemsSym]?: Schema };
-  }
-
-  /**
-   * The timestamp of the creation time of the CoMap
-   */
-  get _createdAt() {
-    return this._raw.earliestTxMadeAt ?? Number.MAX_SAFE_INTEGER;
-  }
-
-  /**
-   * The timestamp of the last updated time of the CoMap
-   */
-  get _lastUpdatedAt() {
-    return this._raw.latestTxMadeAt;
+    this.prototype[TypeSym] = "CoMap";
   }
 
   /**
-   * If property `prop` is a `coField.ref(...)`, you can use `coMaps._refs.prop` to access
-   * the `Ref` instead of the potentially loaded/null value.
-   *
-   * This allows you to always get the ID or load the value manually.
-   *
-   * @example
-   * ```ts
-   * person._refs.pet.id; // => ID<Animal>
-   * person._refs.pet.value;
-   * // => Animal | null
-   * const pet = await person._refs.pet.load();
-   * ```
+   * Jazz methods for CoMaps are inside this property.
    *
-   * @category Content
-   **/
-  get _refs(): Simplify<
-    {
-      [Key in CoKeys<this> as NonNullable<this[Key]> extends CoValue
-        ? Key
-        : never]?: RefIfCoValue<this[Key]>;
-    } & {
-      [Key in CoKeys<this> as this[Key] extends undefined
-        ? never
-        : this[Key] extends CoValue
-          ? Key
-          : never]: RefIfCoValue<this[Key]>;
-    }
-  > {
-    return makeRefs<CoKeys<this>>(
-      this,
-      (key) => this._raw.get(key as string) as unknown as ID<CoValue>,
-      () => {
-        const keys = this._raw.keys().filter((key) => {
-          const descriptor = this.getDescriptor(key as string);
-          return (
-            descriptor && descriptor !== "json" && isRefEncoded(descriptor)
-          );
-        }) as CoKeys<this>[];
-
-        return keys;
-      },
-      this._loadedAs,
-      (key) => this.getDescriptor(key as string) as RefEncoded<CoValue>,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    ) as any;
-  }
+   * This allows CoMaps to be used as plain objects while still having
+   * access to Jazz methods, and also doesn't limit which key names can be
+   * used inside CoMaps.
+   */
+  declare $jazz: CoMapJazzApi<this>;
 
   /** @internal */
-  public getEditFromRaw(
-    target: CoMap,
-    rawEdit: {
-      by: RawAccountID | AgentID;
-      tx: CojsonInternalTypes.TransactionID;
-      at: Date;
-      value?: JsonValue | undefined;
-    },
-    descriptor: Schema,
-    key: string,
-  ) {
-    return {
-      value:
-        descriptor === "json"
-          ? rawEdit.value
-          : "encoded" in descriptor
-            ? rawEdit.value === null || rawEdit.value === undefined
-              ? rawEdit.value
-              : descriptor.encoded.decode(rawEdit.value)
-            : accessChildById(target, rawEdit.value as string, descriptor),
-      ref:
-        descriptor !== "json" && isRefEncoded(descriptor)
-          ? new Ref(
-              rawEdit.value as ID<CoValue>,
-              target._loadedAs,
-              descriptor,
-              target,
-            )
-          : undefined,
-      get by() {
-        return (
-          rawEdit.by &&
-          accessChildById(target, rawEdit.by, {
-            ref: Account,
-            optional: false,
-          })
-        );
-      },
-      madeAt: rawEdit.at,
-      key,
-    };
-  }
-
-  /** @category Collaboration */
-  get _edits() {
-    const map = this;
-    return new Proxy(
-      {},
-      {
-        get(_target, key) {
-          const rawEdit = map._raw.lastEditAt(key as string);
-          if (!rawEdit) return undefined;
-
-          const descriptor = map.getDescriptor(key as string);
-
-          if (!descriptor) return undefined;
-
-          return {
-            ...map.getEditFromRaw(map, rawEdit, descriptor, key as string),
-            get all() {
-              return [...map._raw.editsAt(key as string)].map((rawEdit) =>
-                map.getEditFromRaw(map, rawEdit, descriptor, key as string),
-              );
-            },
-          };
-        },
-        ownKeys(_target) {
-          return map._raw.keys();
-        },
-        getOwnPropertyDescriptor(target, key) {
-          return {
-            value: Reflect.get(target, key),
-            writable: false,
-            enumerable: true,
-            configurable: true,
-          };
-        },
-      },
-    ) as {
-      [Key in CoKeys<this>]?: LastAndAllCoMapEdits<this[Key]>;
-    };
-  }
+  static _schema: CoMapFieldSchema;
 
   /** @internal */
-  constructor(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    options: { fromRaw: RawCoMap } | undefined,
-  ) {
+  constructor(options: { fromRaw: RawCoMap } | undefined) {
     super();
 
+    const proxy = new Proxy(this, CoMapProxyHandler as ProxyHandler<this>);
+
     if (options) {
       if ("fromRaw" in options) {
         Object.defineProperties(this, {
-          id: {
-            value: options.fromRaw.id as unknown as ID<this>,
+          $jazz: {
+            value: new CoMapJazzApi(proxy, () => options.fromRaw),
             enumerable: false,
           },
-          _raw: { value: options.fromRaw, enumerable: false },
         });
       } else {
         throw new Error("Invalid CoMap constructor arguments");
       }
     }
 
-    return new Proxy(this, CoMapProxyHandler as ProxyHandler<this>);
+    return proxy;
   }
 
   /**
@@ -300,13 +160,15 @@ export class CoMap extends CoValueBase implements CoValue {
    * ```
    *
    * @category Creation
+   *
+   * @deprecated Use `co.map(...).create`.
    **/
   static create<M extends CoMap>(
     this: CoValueClass<M>,
-    init: Simplify<CoMapInit<M>>,
+    init: Simplify<CoMapInit_DEPRECATED<M>>,
     options?:
       | {
-          owner: Account | Group;
+          owner?: Account | Group;
           unique?: CoValueUniqueness["uniqueness"];
         }
       | Account
@@ -314,7 +176,7 @@ export class CoMap extends CoValueBase implements CoValue {
   ) {
     const instance = new this();
 
-    return instance._createCoMap(init, options);
+    return CoMap._createCoMap(instance, init, options);
   }
 
   /**
@@ -323,25 +185,22 @@ export class CoMap extends CoValueBase implements CoValue {
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   toJSON(_key?: string, processedValues?: ID<CoValue>[]): any {
-    const result = {
-      id: this.id,
-      _type: this._type,
-    } as Record<string, any>;
+    const result = {} as Record<string, any>;
 
-    for (const key of this._raw.keys()) {
+    for (const key of this.$jazz.raw.keys()) {
       const tKey = key as CoKeys<this>;
-      const descriptor = this.getDescriptor(tKey);
+      const descriptor = this.$jazz.getDescriptor(tKey);
 
       if (!descriptor) {
         continue;
       }
 
       if (descriptor == "json" || "encoded" in descriptor) {
-        result[key] = this._raw.get(key);
+        result[key] = this.$jazz.raw.get(key);
       } else if (isRefEncoded(descriptor)) {
-        const id = this._raw.get(key) as ID<CoValue>;
+        const id = this.$jazz.raw.get(key) as ID<CoValue>;
 
-        if (processedValues?.includes(id) || id === this.id) {
+        if (processedValues?.includes(id) || id === this.$jazz.id) {
           result[key] = { _circular: id };
           continue;
         }
@@ -356,7 +215,7 @@ export class CoMap extends CoValueBase implements CoValue {
         ) {
           const jsonedRef = ref.toJSON(tKey, [
             ...(processedValues || []),
-            this.id,
+            this.$jazz.id,
           ]);
           result[key] = jsonedRef;
         }
@@ -372,41 +231,45 @@ export class CoMap extends CoValueBase implements CoValue {
     return this.toJSON();
   }
 
-  _createCoMap(
-    init: Simplify<CoMapInit<typeof this>>,
+  /**
+   * @internal
+   */
+  static _createCoMap<M extends CoMap>(
+    instance: M,
+    init: Simplify<CoMapInit_DEPRECATED<M>>,
     options?:
       | {
-          owner: Account | Group;
+          owner?: Account | Group;
           unique?: CoValueUniqueness["uniqueness"];
         }
       | Account
       | Group,
-  ): typeof this {
+  ): M {
     const { owner, uniqueness } = parseCoValueCreateOptions(options);
-    const raw = this.rawFromInit(init, owner, uniqueness);
 
-    Object.defineProperties(this, {
-      id: {
-        value: raw.id,
+    Object.defineProperties(instance, {
+      $jazz: {
+        value: new CoMapJazzApi(instance, () => raw),
         enumerable: false,
       },
-      _raw: { value: raw, enumerable: false },
     });
 
-    return this;
+    const raw = CoMap.rawFromInit(instance, init, owner, uniqueness);
+
+    return instance;
   }
 
   /**
    * Create a new `RawCoMap` from an initialization object
    * @internal
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  rawFromInit<Fields extends object = Record<string, any>>(
-    init: Simplify<CoMapInit<Fields>> | undefined,
-    owner: Account | Group,
+  static rawFromInit<M extends CoMap, Fields extends object>(
+    instance: M,
+    init: Simplify<CoMapInit_DEPRECATED<Fields>> | undefined,
+    owner: Group,
     uniqueness?: CoValueUniqueness,
   ) {
-    const rawOwner = owner._raw;
+    const rawOwner = owner.$jazz.raw;
 
     const rawInit = {} as {
       [key in keyof Fields]: JsonValue | undefined;
@@ -416,7 +279,7 @@ export class CoMap extends CoValueBase implements CoValue {
       for (const key of Object.keys(init) as (keyof Fields)[]) {
         const initValue = init[key as keyof typeof init];
 
-        const descriptor = this.getDescriptor(key as string);
+        const descriptor = instance.$jazz.getDescriptor(key as string);
 
         if (!descriptor) {
           continue;
@@ -426,14 +289,14 @@ export class CoMap extends CoValueBase implements CoValue {
           rawInit[key] = initValue as JsonValue;
         } else if (isRefEncoded(descriptor)) {
           if (initValue != null) {
-            let refId = (initValue as unknown as CoValue).id;
+            let refId = (initValue as unknown as CoValue).$jazz?.id;
             if (!refId) {
               const coValue = instantiateRefEncodedWithInit(
                 descriptor,
                 initValue,
                 owner,
               );
-              refId = coValue.id;
+              refId = coValue.$jazz.id;
             }
             rawInit[key] = refId;
           }
@@ -448,10 +311,6 @@ export class CoMap extends CoValueBase implements CoValue {
     return rawOwner.createMap(rawInit, null, "private", uniqueness);
   }
 
-  getDescriptor(key: string) {
-    return this._schema?.[key] || this._schema?.[ItemsSym];
-  }
-
   /**
    * Declare a Record-like CoMap schema, by extending `CoMap.Record(...)` and passing the value schema using `co`. Keys are always `string`.
    *
@@ -500,6 +359,8 @@ export class CoMap extends CoValueBase implements CoValue {
    * ```
    *
    * @category Subscription & Loading
+   *
+   * @deprecated Use `co.map(...).load` instead.
    */
   static load<M extends CoMap, const R extends RefsToResolve<M> = true>(
     this: CoValueClass<M>,
@@ -539,6 +400,8 @@ export class CoMap extends CoValueBase implements CoValue {
    * ```
    *
    * @category Subscription & Loading
+   *
+   * @deprecated Use `co.map(...).subscribe` instead.
    */
   static subscribe<M extends CoMap, const R extends RefsToResolve<M> = true>(
     this: CoValueClass<M>,
@@ -589,7 +452,7 @@ export class CoMap extends CoValueBase implements CoValue {
       uniqueness: unique,
     };
     const crypto =
-      as._type === "Anonymous" ? as.node.crypto : as._raw.core.node.crypto;
+      as[TypeSym] === "Anonymous" ? as.node.crypto : as.$jazz.localNode.crypto;
     return cojsonInternals.idforHeader(header, crypto) as ID<M>;
   }
 
@@ -615,6 +478,8 @@ export class CoMap extends CoValueBase implements CoValue {
    * @param options The options for creating or loading the CoMap. This includes the intended state of the CoMap, its unique identifier, its owner, and the references to resolve.
    * @returns Either an existing & modified CoMap, or a new initialised CoMap if none exists.
    * @category Subscription & Loading
+   *
+   * @deprecated Use `co.map(...).upsertUnique` instead.
    */
   static async upsertUnique<
     M extends CoMap,
@@ -622,7 +487,7 @@ export class CoMap extends CoValueBase implements CoValue {
   >(
     this: CoValueClass<M>,
     options: {
-      value: Simplify<CoMapInit<M>>;
+      value: Simplify<CoMapInit_DEPRECATED<M>>;
       unique: CoValueUniqueness["uniqueness"];
       owner: Account | Group;
       resolve?: RefsToResolveStrict<M, R>;
@@ -630,27 +495,29 @@ export class CoMap extends CoValueBase implements CoValue {
   ): Promise<Resolved<M, R> | null> {
     const mapId = CoMap._findUnique(
       options.unique,
-      options.owner.id,
-      options.owner._loadedAs,
+      options.owner.$jazz.id,
+      options.owner.$jazz.loadedAs,
     );
     let map: Resolved<M, R> | null = await loadCoValueWithoutMe(this, mapId, {
       ...options,
-      loadAs: options.owner._loadedAs,
+      loadAs: options.owner.$jazz.loadedAs,
       skipRetry: true,
     });
     if (!map) {
       const instance = new this();
-      map = instance._createCoMap(options.value, {
+      map = CoMap._createCoMap(instance, options.value, {
         owner: options.owner,
         unique: options.unique,
       }) as Resolved<M, R>;
     } else {
-      (map as M).applyDiff(options.value as Partial<CoMapInit<M>>);
+      (map as M).$jazz.applyDiff(
+        options.value as unknown as Partial<CoMapInit<M>>,
+      );
     }
 
     return await loadCoValueWithoutMe(this, mapId, {
       ...options,
-      loadAs: options.owner._loadedAs,
+      loadAs: options.owner.$jazz.loadedAs,
       skipRetry: true,
     });
   }
@@ -661,6 +528,8 @@ export class CoMap extends CoValueBase implements CoValue {
    * @param ownerID The ID of the owner of the CoMap.
    * @param options Additional options for loading the CoMap.
    * @returns The loaded CoMap, or null if unavailable.
+   *
+   * @deprecated Use `co.map(...).loadUnique` instead.
    */
   static loadUnique<M extends CoMap, const R extends RefsToResolve<M> = true>(
     this: CoValueClass<M>,
@@ -677,48 +546,114 @@ export class CoMap extends CoValueBase implements CoValue {
       { ...options, skipRetry: true },
     );
   }
+}
+
+/**
+ * Contains CoMap Jazz methods that are part of the {@link CoMap.$jazz`} property.
+ */
+class CoMapJazzApi<M extends CoMap> extends CoValueJazzApi<M> {
+  constructor(
+    private coMap: M,
+    private getRaw: () => RawCoMap,
+  ) {
+    super(coMap);
+  }
 
   /**
-   * Given an already loaded `CoMap`, ensure that the specified fields are loaded to the specified depth.
+   * The ID of this `CoMap`
+   * @category Content
+   */
+  get id(): ID<M> {
+    return this.raw.id;
+  }
+
+  get owner(): Group {
+    return getCoValueOwner(this.coMap);
+  }
+
+  /**
+   * Check if a key is defined in the CoMap.
    *
-   * Works like `CoMap.load()`, but you don't need to pass the ID or the account to load as again.
+   * This check does not load the referenced value or validate permissions.
    *
-   * @category Subscription & Loading
+   * @param key The key to check
+   * @returns True if the key is defined, false otherwise
+   * @category Content
    */
-  ensureLoaded<M extends CoMap, const R extends RefsToResolve<M>>(
-    this: M,
-    options: { resolve: RefsToResolveStrict<M, R> },
-  ): Promise<Resolved<M, R>> {
-    return ensureCoValueLoaded(this, options);
+  has(key: CoKeys<M>): boolean {
+    const entry = this.raw.getRaw(key);
+    return entry?.change !== undefined && entry.change.op !== "del";
   }
 
   /**
-   * Given an already loaded `CoMap`, subscribe to updates to the `CoMap` and ensure that the specified fields are loaded to the specified depth.
+   * Set a value on the CoMap
    *
-   * Works like `CoMap.subscribe()`, but you don't need to pass the ID or the account to load as again.
+   * @param key The key to set
+   * @param value The value to set
    *
-   * Returns an unsubscribe function that you should call when you no longer need updates.
+   * @category Content
+   */
+  set<K extends CoKeys<M>>(key: K, value: CoFieldInit<M[K]>): void {
+    const descriptor = this.getDescriptor(key as string);
+
+    if (!descriptor) {
+      throw Error(`Cannot set unknown key ${key}`);
+    }
+
+    let refId = (value as CoValue)?.$jazz?.id;
+    if (descriptor === "json") {
+      this.raw.set(key, value as JsonValue | undefined);
+    } else if ("encoded" in descriptor) {
+      this.raw.set(key, descriptor.encoded.encode(value));
+    } else if (isRefEncoded(descriptor)) {
+      if (value === undefined) {
+        if (!descriptor.optional) {
+          throw Error(`Cannot set required reference ${key} to undefined`);
+        }
+        this.raw.set(key, null);
+      } else {
+        if (!refId) {
+          const coValue = instantiateRefEncodedWithInit(
+            descriptor,
+            value,
+            this.owner,
+          );
+          refId = coValue.$jazz.id;
+        }
+        this.raw.set(key, refId);
+      }
+    }
+  }
+
+  /**
+   * Delete a value from a CoMap.
    *
-   * @category Subscription & Loading
-   **/
-  subscribe<M extends CoMap, const R extends RefsToResolve<M> = true>(
-    this: M,
-    listener: (value: Resolved<M, R>, unsubscribe: () => void) => void,
-  ): () => void;
-  subscribe<M extends CoMap, const R extends RefsToResolve<M> = true>(
-    this: M,
-    options: { resolve?: RefsToResolveStrict<M, R> },
-    listener: (value: Resolved<M, R>, unsubscribe: () => void) => void,
-  ): () => void;
-  subscribe<M extends CoMap, const R extends RefsToResolve<M>>(
-    this: M,
-    ...args: SubscribeRestArgs<M, R>
-  ): () => void {
-    const { options, listener } = parseSubscribeRestArgs(args);
-    return subscribeToExistingCoValue<M, R>(this, options, listener);
+   * For record-like CoMaps (created with `co.record`), any string key can be deleted.
+   * For struct-like CoMaps (created with `co.map`), only optional properties can be deleted.
+   *
+   * @param key The key to delete
+   *
+   * @category Content
+   */
+  delete(
+    key: OptionalCoKeys<M> | (string extends keyof M ? string : never),
+  ): void {
+    this.raw.delete(key);
   }
 
-  applyDiff<N extends Partial<CoMapInit<this>>>(newValues: N) {
+  /**
+   * Modify the `CoMap` to match another map.
+   *
+   * The new values are assigned to the CoMap, overwriting existing values
+   * when the property already exists.
+   *
+   * @param newValues - The new values to apply to the CoMap. For collaborative values,
+   * both CoValues and JSON values are supported.
+   * @returns The modified CoMap.
+   *
+   * @category Content
+   */
+  applyDiff(newValues: Partial<CoMapInit<M>>): M {
     for (const key in newValues) {
       if (Object.prototype.hasOwnProperty.call(newValues, key)) {
         const tKey = key as keyof typeof newValues & keyof this;
@@ -727,24 +662,64 @@ export class CoMap extends CoValueBase implements CoValue {
         if (!descriptor) continue;
 
         const newValue = newValues[tKey];
-        const currentValue = (this as unknown as N)[tKey];
+        const currentValue = this.coMap[tKey];
 
         if (descriptor === "json" || "encoded" in descriptor) {
           if (currentValue !== newValue) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (this as any)[tKey] = newValue;
+            this.set(tKey as any, newValue as CoFieldInit<M[keyof M]>);
           }
         } else if (isRefEncoded(descriptor)) {
-          const currentId = (currentValue as CoValue | undefined)?.id;
-          const newId = (newValue as CoValue | undefined)?.id;
+          const currentId = (currentValue as CoValue | undefined)?.$jazz.id;
+          let newId = (newValue as CoValue | undefined)?.$jazz?.id;
           if (currentId !== newId) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (this as any)[tKey] = newValue;
+            this.set(tKey as any, newValue as CoFieldInit<M[keyof M]>);
           }
         }
       }
     }
-    return this;
+    return this.coMap;
+  }
+
+  /**
+   * Given an already loaded `CoMap`, ensure that the specified fields are loaded to the specified depth.
+   *
+   * Works like `CoMap.load()`, but you don't need to pass the ID or the account to load as again.
+   *
+   * @category Subscription & Loading
+   */
+  ensureLoaded<Map extends CoMap, const R extends RefsToResolve<Map>>(
+    this: CoMapJazzApi<Map>,
+    options: {
+      resolve: RefsToResolveStrict<Map, R>;
+    },
+  ): Promise<Resolved<Map, R>> {
+    return ensureCoValueLoaded(this.coMap, options);
+  }
+
+  /**
+   * Given an already loaded `CoMap`, subscribe to updates to the `CoMap` and ensure that the specified fields are loaded to the specified depth.
+   *
+   * Works like `CoMap.subscribe()`, but you don't need to pass the ID or the account to load as again.
+   *
+   * Returns an unsubscribe function that you should call when you no longer need updates.
+   *
+   * @category Subscription & Loading
+   **/
+  subscribe<Map extends CoMap, const R extends RefsToResolve<Map> = true>(
+    this: CoMapJazzApi<Map>,
+    listener: (value: Resolved<Map, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<Map extends CoMap, const R extends RefsToResolve<Map> = true>(
+    this: CoMapJazzApi<Map>,
+    options: { resolve?: RefsToResolveStrict<Map, R> },
+    listener: (value: Resolved<Map, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<Map extends CoMap, const R extends RefsToResolve<Map>>(
+    this: CoMapJazzApi<Map>,
+    ...args: SubscribeRestArgs<Map, R>
+  ): () => void {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this.coMap, options, listener);
   }
 
   /**
@@ -752,8 +727,134 @@ export class CoMap extends CoValueBase implements CoValue {
    *
    * @category Subscription & Loading
    */
-  waitForSync(options?: { timeout?: number }) {
-    return this._raw.core.waitForSync(options);
+  async waitForSync(options?: { timeout?: number }): Promise<void> {
+    await this.raw.core.waitForSync(options);
+  }
+
+  /**
+   * Get the descriptor for a given key
+   * @internal
+   */
+  getDescriptor(key: string): Schema | undefined {
+    return this.schema?.[key] || this.schema?.[ItemsSym];
+  }
+
+  /**
+   * If property `prop` is a `coField.ref(...)`, you can use `coMap.$jazz.refs.prop` to access
+   * the `Ref` instead of the potentially loaded/null value.
+   *
+   * This allows you to always get the ID or load the value manually.
+   *
+   * @example
+   * ```ts
+   * person.$jazz.refs.pet.id; // => ID<Animal>
+   * person.$jazz.refs.pet.value;
+   * // => Animal | null
+   * const pet = await person.$jazz.refs.pet.load();
+   * ```
+   *
+   * @category Content
+   **/
+  get refs(): Simplify<
+    {
+      [Key in CoKeys<M> as NonNullable<M[Key]> extends CoValue
+        ? Key
+        : never]?: RefIfCoValue<M[Key]>;
+    } & {
+      [Key in CoKeys<M> as M[Key] extends undefined
+        ? never
+        : M[Key] extends CoValue
+          ? Key
+          : never]: RefIfCoValue<M[Key]>;
+    }
+  > {
+    return makeRefs<CoKeys<this>>(
+      this.coMap,
+      (key) => this.raw.get(key as string) as unknown as ID<CoValue>,
+      () => {
+        const keys = this.raw.keys().filter((key) => {
+          const descriptor = this.getDescriptor(key as string);
+          return (
+            descriptor && descriptor !== "json" && isRefEncoded(descriptor)
+          );
+        }) as CoKeys<this>[];
+
+        return keys;
+      },
+      this.loadedAs,
+      (key) => this.getDescriptor(key as string) as RefEncoded<CoValue>,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) as any;
+  }
+
+  /**
+   * Get the edits made to the CoMap.
+   *
+   * @category Collaboration
+   */
+  getEdits(): CoMapEdits<M> {
+    const map = this.coMap;
+    return new Proxy(
+      {},
+      {
+        get(_target, key) {
+          const rawEdit = map.$jazz.raw.lastEditAt(key as string);
+          if (!rawEdit) return undefined;
+
+          const descriptor = map.$jazz.getDescriptor(key as string);
+
+          if (!descriptor) return undefined;
+
+          return {
+            ...getEditFromRaw(map, rawEdit, descriptor, key as string),
+            get all() {
+              return [...map.$jazz.raw.editsAt(key as string)].map((rawEdit) =>
+                getEditFromRaw(map, rawEdit, descriptor, key as string),
+              );
+            },
+          };
+        },
+        ownKeys(_target) {
+          return map.$jazz.raw.keys();
+        },
+        getOwnPropertyDescriptor(target, key) {
+          return {
+            value: Reflect.get(target, key),
+            writable: false,
+            enumerable: true,
+            configurable: true,
+          };
+        },
+      },
+    );
+  }
+
+  /** @internal */
+  override get raw() {
+    return this.getRaw();
+  }
+
+  /**
+   * The timestamp of the creation time of the CoMap
+   *
+   * @category Content
+   */
+  get createdAt(): number {
+    return this.raw.earliestTxMadeAt ?? Number.MAX_SAFE_INTEGER;
+  }
+
+  /**
+   * The timestamp of the last updated time of the CoMap
+   *
+   * @category Content
+   */
+  get lastUpdatedAt(): number {
+    return this.raw.latestTxMadeAt;
+  }
+
+  /** @internal */
+  get schema(): CoMapFieldSchema {
+    return (this.coMap.constructor as typeof CoMap)._schema;
   }
 }
 
@@ -762,6 +863,20 @@ export type CoKeys<Map extends object> = Exclude<
   keyof CoMap
 >;
 
+/**
+ * Extract keys of properties that are required
+ */
+export type RequiredCoKeys<Map extends object> = {
+  [K in CoKeys<Map>]: undefined extends Map[K] ? never : K;
+}[CoKeys<Map>];
+
+/**
+ * Extract keys of properties that can be undefined
+ */
+export type OptionalCoKeys<Map extends object> = {
+  [K in CoKeys<Map>]: undefined extends Map[K] ? K : never;
+}[CoKeys<Map>];
+
 /**
  * Force required ref fields to be non nullable
  *
@@ -793,10 +908,16 @@ type ForceRequiredRef<V> = V extends InstanceType<CoValueClass> | null
     ? V | null
     : V;
 
-export type CoMapInit<Map extends object> = PartialOnUndefined<{
+export type CoMapInit_DEPRECATED<Map extends object> = PartialOnUndefined<{
   [Key in CoKeys<Map>]: ForceRequiredRef<Map[Key]>;
 }>;
 
+export type CoMapInit<Map extends object> = {
+  [K in RequiredCoKeys<Map>]: CoFieldInit<Map[K]>;
+} & {
+  [K in OptionalCoKeys<Map>]?: CoFieldInit<Map[K]> | undefined;
+};
+
 // TODO: cache handlers per descriptor for performance?
 const CoMapProxyHandler: ProxyHandler<CoMap> = {
   get(target, key, receiver) {
@@ -809,13 +930,13 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
         return undefined;
       }
 
-      const descriptor = target.getDescriptor(key as string);
+      const descriptor = target.$jazz.getDescriptor(key as string);
 
       if (!descriptor) {
         return undefined;
       }
 
-      const raw = target._raw.get(key);
+      const raw = target.$jazz.raw.get(key);
 
       if (descriptor === "json") {
         return raw;
@@ -830,7 +951,7 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
   },
   set(target, key, value, receiver) {
     if (
-      (typeof key === "string" || ItemsSym) &&
+      typeof key === "string" &&
       typeof value === "object" &&
       value !== null &&
       SchemaInit in value
@@ -840,33 +961,12 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
       return true;
     }
 
-    const descriptor = target.getDescriptor(key as string);
+    const descriptor = target.$jazz.getDescriptor(key as string);
 
     if (!descriptor) return false;
 
     if (typeof key === "string") {
-      if (descriptor === "json") {
-        target._raw.set(key, value);
-      } else if ("encoded" in descriptor) {
-        target._raw.set(key, descriptor.encoded.encode(value));
-      } else if (isRefEncoded(descriptor)) {
-        if (value === undefined) {
-          if (descriptor.optional) {
-            target._raw.set(key, null);
-          } else {
-            throw new Error(
-              `Cannot set required reference ${key} to undefined`,
-            );
-          }
-        } else if (value?.id) {
-          target._raw.set(key, value.id);
-        } else {
-          throw new Error(
-            `Cannot set reference ${key} to a non-CoValue. Got ${value}`,
-          );
-        }
-      }
-      return true;
+      throw Error("Cannot update a CoMap directly. Use `$jazz.set` instead.");
     } else {
       return Reflect.set(target, key, value, receiver);
     }
@@ -888,7 +988,7 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
   ownKeys(target) {
     const keys = Reflect.ownKeys(target).filter((k) => k !== ItemsSym);
 
-    for (const key of target._raw.keys()) {
+    for (const key of target.$jazz.raw.keys()) {
       if (!keys.includes(key)) {
         keys.push(key);
       }
@@ -900,9 +1000,9 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
     if (key in target) {
       return Reflect.getOwnPropertyDescriptor(target, key);
     } else {
-      const descriptor = target.getDescriptor(key as string);
+      const descriptor = target.$jazz.getDescriptor(key as string);
 
-      if (descriptor || key in target._raw.latest) {
+      if (descriptor || key in target.$jazz.raw.latest) {
         return {
           enumerable: true,
           configurable: true,
@@ -912,20 +1012,24 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
     }
   },
   has(target, key) {
-    const descriptor = target.getDescriptor(key as string);
+    // The `has` trap can be called when defining properties during CoMap creation
+    // when using the class-based syntax. In that case, $jazz may not yet be initialized,
+    // as it's defined afterwards in the create method.
+    const descriptor = target.$jazz?.getDescriptor(key as string);
 
-    if (target._raw && typeof key === "string" && descriptor) {
-      return target._raw.get(key) !== undefined;
+    if (target.$jazz?.raw && typeof key === "string" && descriptor) {
+      return target.$jazz.raw.get(key) !== undefined;
     } else {
       return Reflect.has(target, key);
     }
   },
   deleteProperty(target, key) {
-    const descriptor = target.getDescriptor(key as string);
+    const descriptor = target.$jazz.getDescriptor(key as string);
 
     if (typeof key === "string" && descriptor) {
-      target._raw.delete(key);
-      return true;
+      throw Error(
+        "Cannot delete a CoMap property directly. Use `$jazz.delete` instead.",
+      );
     } else {
       return Reflect.deleteProperty(target, key);
     }
@@ -933,3 +1037,47 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
 };
 
 RegisteredSchemas["CoMap"] = CoMap;
+
+/** @internal */
+function getEditFromRaw(
+  target: CoMap,
+  rawEdit: {
+    by: RawAccountID | AgentID;
+    tx: CojsonInternalTypes.TransactionID;
+    at: Date;
+    value?: JsonValue | undefined;
+  },
+  descriptor: Schema,
+  key: string,
+) {
+  return {
+    value:
+      descriptor === "json"
+        ? rawEdit.value
+        : "encoded" in descriptor
+          ? rawEdit.value === null || rawEdit.value === undefined
+            ? rawEdit.value
+            : descriptor.encoded.decode(rawEdit.value)
+          : accessChildById(target, rawEdit.value as string, descriptor),
+    ref:
+      descriptor !== "json" && isRefEncoded(descriptor)
+        ? new Ref(
+            rawEdit.value as ID<CoValue>,
+            target.$jazz.loadedAs,
+            descriptor,
+            target,
+          )
+        : undefined,
+    get by() {
+      return (
+        rawEdit.by &&
+        accessChildById(target, rawEdit.by, {
+          ref: Account,
+          optional: false,
+        })
+      );
+    },
+    madeAt: rawEdit.at,
+    key,
+  };
+}