jazz-tools 0.17.13 → 0.18.0

package/src/tools/coValues/coList.ts

@@ -1,11 +1,13 @@
-import type { JsonValue, RawCoList, CoValueUniqueness, RawCoID } from "cojson";
-import { ControlledAccount, RawAccount, cojsonInternals } from "cojson";
+import type { CoValueUniqueness, JsonValue, RawCoID, RawCoList } from "cojson";
+import { cojsonInternals } from "cojson";
 import { calcPatch } from "fast-myers-diff";
-import type {
+import {
   Account,
+  CoFieldInit,
   CoValue,
   CoValueClass,
-  CoValueFromRaw,
+  CoValueJazzApi,
+  getCoValueOwner,
   Group,
   ID,
   RefEncoded,
@@ -16,18 +18,16 @@ import type {
   SchemaFor,
   SubscribeListenerOptions,
   SubscribeRestArgs,
+  TypeSym,
 } from "../internal.js";
 import {
   AnonymousJazzAgent,
   ItemsSym,
   Ref,
-  RegisteredSchemas,
   SchemaInit,
   accessChildByKey,
   activeAccountContext,
   coField,
-  coValueClassFromCoValueClassOrSchema,
-  coValuesCache,
   ensureCoValueLoaded,
   inspect,
   instantiateRefEncodedWithInit,
@@ -46,19 +46,28 @@ import {
  * @categoryDescription Content
  * You can access items on a `CoList` as if they were normal items on a plain array, using `[]` notation, etc.
  *
- * Since `CoList` is a subclass of `Array`, you can use all the normal array methods like `push`, `pop`, `splice`, etc.
+ * All readonly array methods are available on `CoList`. You can also use the `.$jazz` API to mutate the CoList.
+ *
+ * ```ts
+ * const colorList = ColorList.create(["red", "green", "blue"]);
+ * ```
  *
  * ```ts
  * colorList[0];
- * colorList[3] = "yellow";
- * colorList.push("Kawazaki Green");
- * colorList.splice(1, 1);
+ * colorList.$jazz.set(3, "yellow");
+ * colorList.$jazz.push("Kawazaki Green");
+ * colorList.$jazz.splice(1, 1);
  * ```
  *
  * @category CoValues
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export class CoList<out Item = any> extends Array<Item> implements CoValue {
+export class CoList<out Item = any>
+  extends Array<Item>
+  implements ReadonlyArray<Item>, CoValue
+{
+  declare $jazz: CoListJazzApi<this>;
+
   /**
    * Declare a `CoList` by subclassing `CoList.Of(...)` and passing the item schema using `co`.
    *
@@ -88,129 +97,37 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
     throw new Error("Can't use Array.of with CoLists");
   }
 
-  /**
-   * The ID of this `CoList`
-   * @category Content */
-  declare id: ID<this>;
   /** @category Type Helpers */
-  declare _type: "CoList";
+  declare [TypeSym]: "CoList";
   static {
-    this.prototype._type = "CoList";
+    this.prototype[TypeSym] = "CoList";
   }
-  /** @category Internals */
-  declare _raw: RawCoList;
-  /** @category Internals */
-  declare _instanceID: string;
 
   /** @internal This is only a marker type and doesn't exist at runtime */
   [ItemsSym]!: Item;
   /** @internal */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   static _schema: any;
-  /** @internal */
-  get _schema(): {
-    [ItemsSym]: SchemaFor<Item> | any;
-  } {
-    return (this.constructor as typeof CoList)._schema;
-  }
-
-  /** @category Collaboration */
-  get _owner(): Account | Group {
-    return this._raw.group instanceof RawAccount
-      ? coValueClassFromCoValueClassOrSchema(
-          RegisteredSchemas["Account"],
-        ).fromRaw(this._raw.group)
-      : RegisteredSchemas["Group"].fromRaw(this._raw.group);
-  }
-
-  /**
-   * If a `CoList`'s items are a `coField.ref(...)`, you can use `coList._refs[i]` 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
-   * animals._refs[0].id; // => ID<Animal>
-   * animals._refs[0].value;
-   * // => Animal | null
-   * const animal = await animals._refs[0].load();
-   * ```
-   *
-   * @category Content
-   **/
-  get _refs(): {
-    [idx: number]: Exclude<Item, null> extends CoValue
-      ? Ref<Exclude<Item, null>>
-      : never;
-  } & {
-    length: number;
-    [Symbol.iterator](): IterableIterator<
-      Exclude<Item, null> extends CoValue ? Ref<Exclude<Item, null>> : never
-    >;
-  } {
-    return makeRefs<number>(
-      this,
-      (idx) => this._raw.get(idx) as unknown as ID<CoValue>,
-      () => Array.from({ length: this._raw.entries().length }, (_, idx) => idx),
-      this._loadedAs,
-      (_idx) => this._schema[ItemsSym] as RefEncoded<CoValue>,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    ) as any;
-  }
-
-  get _edits(): {
-    [idx: number]: {
-      value?: Item;
-      ref?: Item extends CoValue ? Ref<Item> : never;
-      by: Account | null;
-      madeAt: Date;
-    };
-  } {
-    throw new Error("Not implemented");
-  }
-
-  get _loadedAs() {
-    const agent = this._raw.core.node.getCurrentAgent();
-
-    if (agent instanceof ControlledAccount) {
-      return coValuesCache.get(agent.account, () =>
-        coValueClassFromCoValueClassOrSchema(
-          RegisteredSchemas["Account"],
-        ).fromRaw(agent.account),
-      );
-    }
-
-    return new AnonymousJazzAgent(this._raw.core.node);
-  }
 
   static get [Symbol.species]() {
     return Array;
   }
 
-  getItemsDescriptor() {
-    return this._schema?.[ItemsSym];
-  }
-
   constructor(options: { fromRaw: RawCoList } | undefined) {
     super();
 
-    Object.defineProperty(this, "_instanceID", {
-      value: `instance-${Math.random().toString(36).slice(2)}`,
-      enumerable: false,
-    });
+    const proxy = new Proxy(this, CoListProxyHandler as ProxyHandler<this>);
 
     if (options && "fromRaw" in options) {
       Object.defineProperties(this, {
-        id: {
-          value: options.fromRaw.id,
+        $jazz: {
+          value: new CoListJazzApi(proxy, () => options.fromRaw),
           enumerable: false,
         },
-        _raw: { value: options.fromRaw, enumerable: false },
       });
     }
 
-    return new Proxy(this, CoListProxyHandler as ProxyHandler<this>);
+    return proxy;
   }
 
   /**
@@ -233,6 +150,7 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
    * ```
    *
    * @category Creation
+   * @deprecated Use `co.list(...).create` instead.
    **/
   static create<L extends CoList>(
     this: CoValueClass<L>,
@@ -246,159 +164,41 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
       | Group,
   ) {
     const { owner, uniqueness } = parseCoValueCreateOptions(options);
-    const instance = new this({ init: items, owner });
-    const raw = owner._raw.createList(
-      toRawItems(items, instance._schema[ItemsSym], owner),
-      null,
-      "private",
-      uniqueness,
-    );
+    const instance = new this();
 
     Object.defineProperties(instance, {
-      id: {
-        value: raw.id,
+      $jazz: {
+        value: new CoListJazzApi(instance, () => raw),
         enumerable: false,
       },
-      _raw: { value: raw, enumerable: false },
     });
 
-    return instance;
-  }
-
-  push(...items: Item[]): number {
-    this._raw.appendItems(
-      toRawItems(items, this._schema[ItemsSym], this._owner),
-      undefined,
+    const raw = owner.$jazz.raw.createList(
+      toRawItems(items, instance.$jazz.schema[ItemsSym], owner),
+      null,
       "private",
+      uniqueness,
     );
 
-    return this._raw.entries().length;
-  }
-
-  unshift(...items: Item[]): number {
-    for (const item of toRawItems(
-      items as Item[],
-      this._schema[ItemsSym],
-      this._owner,
-    )) {
-      this._raw.prepend(item);
-    }
-
-    return this._raw.entries().length;
-  }
-
-  pop(): Item | undefined {
-    const last = this[this.length - 1];
-
-    this._raw.delete(this.length - 1);
-
-    return last;
-  }
-
-  shift(): Item | undefined {
-    const first = this[0];
-
-    this._raw.delete(0);
-
-    return first;
-  }
-
-  /**
-   * Splice the `CoList` at a given index.
-   *
-   * @param start - The index to start the splice.
-   * @param deleteCount - The number of items to delete.
-   * @param items - The items to insert.
-   */
-  splice(start: number, deleteCount: number, ...items: Item[]): Item[] {
-    const deleted = this.slice(start, start + deleteCount);
-
-    for (
-      let idxToDelete = start + deleteCount - 1;
-      idxToDelete >= start;
-      idxToDelete--
-    ) {
-      this._raw.delete(idxToDelete);
-    }
-
-    const rawItems = toRawItems(
-      items as Item[],
-      this._schema[ItemsSym],
-      this._owner,
-    );
-
-    // If there are no items to insert, return the deleted items
-    if (rawItems.length === 0) {
-      return deleted;
-    }
-
-    // Fast path for single item insertion
-    if (rawItems.length === 1) {
-      const item = rawItems[0];
-      if (item === undefined) return deleted;
-      if (start === 0) {
-        this._raw.prepend(item);
-      } else {
-        this._raw.append(item, Math.max(start - 1, 0));
-      }
-      return deleted;
-    }
-
-    // Handle multiple items
-    if (start === 0) {
-      // Iterate in reverse order without creating a new array
-      for (let i = rawItems.length - 1; i >= 0; i--) {
-        const item = rawItems[i];
-        if (item === undefined) continue;
-        this._raw.prepend(item);
-      }
-    } else {
-      let appendAfter = Math.max(start - 1, 0);
-      for (const item of rawItems) {
-        if (item === undefined) continue;
-        this._raw.append(item, appendAfter);
-        appendAfter++;
-      }
-    }
-
-    return deleted;
-  }
-
-  /**
-   * Modify the `CoList` to match another list, where the changes are managed internally.
-   *
-   * @param result - The resolved list of items.
-   */
-  applyDiff(result: Item[]) {
-    const current = this._raw.asArray() as Item[];
-    const comparator = isRefEncoded(this._schema[ItemsSym])
-      ? (aIdx: number, bIdx: number) => {
-          return (
-            (current[aIdx] as CoValue)?.id === (result[bIdx] as CoValue)?.id
-          );
-        }
-      : undefined;
-
-    const patches = [...calcPatch(current, result, comparator)];
-    for (const [from, to, insert] of patches.reverse()) {
-      this.splice(from, to - from, ...insert);
-    }
+    return instance;
   }
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   toJSON(_key?: string, seenAbove?: ID<CoValue>[]): any[] {
-    const itemDescriptor = this._schema[ItemsSym] as Schema;
+    const itemDescriptor = this.$jazz.schema[ItemsSym] as Schema;
     if (itemDescriptor === "json") {
-      return this._raw.asArray();
+      return this.$jazz.raw.asArray();
     } else if ("encoded" in itemDescriptor) {
-      return this._raw.asArray().map((e) => itemDescriptor.encoded.encode(e));
+      return this.$jazz.raw
+        .asArray()
+        .map((e) => itemDescriptor.encoded.encode(e));
     } else if (isRefEncoded(itemDescriptor)) {
       return this.map((item, idx) =>
-        seenAbove?.includes((item as CoValue)?.id)
-          ? { _circular: (item as CoValue).id }
+        seenAbove?.includes((item as CoValue)?.$jazz.id)
+          ? { _circular: (item as CoValue).$jazz.id }
           : (item as unknown as CoValue)?.toJSON(idx + "", [
               ...(seenAbove || []),
-              this.id,
+              this.$jazz.id,
             ]),
       );
     } else {
@@ -422,7 +222,7 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
   static schema<V extends CoList>(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     this: { new (...args: any): V } & typeof CoList,
-    def: { [ItemsSym]: V["_schema"][ItemsSym] },
+    def: { [ItemsSym]: V["$jazz"]["schema"][ItemsSym] },
   ) {
     this._schema ||= {};
     Object.assign(this._schema, def);
@@ -449,6 +249,7 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
    * ```
    *
    * @category Subscription & Loading
+   * @deprecated Use `co.list(...).load` instead.
    */
   static load<L extends CoList, const R extends RefsToResolve<L> = true>(
     this: CoValueClass<L>,
@@ -488,6 +289,7 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
    * ```
    *
    * @category Subscription & Loading
+   * @deprecated Use `co.list(...).subscribe` instead.
    */
   static subscribe<L extends CoList, const R extends RefsToResolve<L> = true>(
     this: CoValueClass<L>,
@@ -509,53 +311,6 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
     return subscribeToCoValueWithoutMe<L, R>(this, id, options, listener);
   }
 
-  /**
-   * Given an already loaded `CoList`, ensure that items are loaded to the specified depth.
-   *
-   * Works like `CoList.load()`, but you don't need to pass the ID or the account to load as again.
-   *
-   * @category Subscription & Loading
-   */
-  ensureLoaded<L extends CoList, const R extends RefsToResolve<L>>(
-    this: L,
-    options: { resolve: RefsToResolveStrict<L, R> },
-  ): Promise<Resolved<L, R>> {
-    return ensureCoValueLoaded(this, options);
-  }
-
-  /**
-   * Given an already loaded `CoList`, subscribe to updates to the `CoList` and ensure that items are loaded to the specified depth.
-   *
-   * Works like `CoList.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<L extends CoList, const R extends RefsToResolve<L> = true>(
-    this: L,
-    listener: (value: Resolved<L, R>, unsubscribe: () => void) => void,
-  ): () => void;
-  subscribe<L extends CoList, const R extends RefsToResolve<L> = true>(
-    this: L,
-    options: { resolve?: RefsToResolveStrict<L, R> },
-    listener: (value: Resolved<L, R>, unsubscribe: () => void) => void,
-  ): () => void;
-  subscribe<L extends CoList, const R extends RefsToResolve<L>>(
-    this: L,
-    ...args: SubscribeRestArgs<L, R>
-  ): () => void {
-    const { options, listener } = parseSubscribeRestArgs(args);
-    return subscribeToExistingCoValue(this, options, listener);
-  }
-
-  /** @category Type Helpers */
-  castAs<Cl extends CoValueClass & CoValueFromRaw<CoValue>>(
-    cl: Cl,
-  ): InstanceType<Cl> {
-    return cl.fromRaw(this._raw) as InstanceType<Cl>;
-  }
-
   /** @deprecated Use `CoList.upsertUnique` and `CoList.loadUnique` instead. */
   static findUnique<L extends CoList>(
     this: CoValueClass<L>,
@@ -585,7 +340,7 @@ export class CoList<out Item = any> extends Array<Item> 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<L>;
   }
 
@@ -623,12 +378,12 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
   ): Promise<Resolved<L, R> | null> {
     const listId = CoList._findUnique(
       options.unique,
-      options.owner.id,
-      options.owner._loadedAs,
+      options.owner.$jazz.id,
+      options.owner.$jazz.loadedAs,
     );
     let list: Resolved<L, R> | null = await loadCoValueWithoutMe(this, listId, {
       ...options,
-      loadAs: options.owner._loadedAs,
+      loadAs: options.owner.$jazz.loadedAs,
       skipRetry: true,
     });
     if (!list) {
@@ -637,12 +392,12 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
         unique: options.unique,
       }) as Resolved<L, R>;
     } else {
-      (list as L).applyDiff(options.value);
+      (list as L).$jazz.applyDiff(options.value);
     }
 
     return await loadCoValueWithoutMe(this, listId, {
       ...options,
-      loadAs: options.owner._loadedAs,
+      loadAs: options.owner.$jazz.loadedAs,
       skipRetry: true,
     });
   }
@@ -670,13 +425,453 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
     );
   }
 
+  // Override mutation methods defined on Array, as CoLists aren't meant to be mutated directly
+  /**
+   * @deprecated Use `.$jazz.push` instead.
+   */
+  override push(...items: never): never {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.$jazz.push` instead.",
+    );
+  }
+  /**
+   * @deprecated Use `.$jazz.unshift` instead.
+   */
+  override unshift(...items: never): number {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.$jazz.unshift` instead.",
+    );
+  }
+  /**
+   * @deprecated Use `.$jazz.pop` instead.
+   */
+  // @ts-expect-error
+  override pop(value: never): never {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.$jazz.pop` instead.",
+    );
+  }
+  /**
+   * @deprecated Use `.$jazz.shift` instead.
+   */
+  // @ts-expect-error
+  override shift(value: never): never {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.$jazz.shift` instead.",
+    );
+  }
+  /**
+   * @deprecated Use `.$jazz.splice` instead.
+   */
+  override splice(start: never, deleteCount: never, ...items: never): never {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.$jazz.splice` instead.",
+    );
+  }
+  /**
+   * @deprecated Use `.$jazz.set` instead.
+   */
+  override copyWithin(target: never, start: never, end: never): never {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.$jazz.set` instead.",
+    );
+  }
+  /**
+   * @deprecated Use `.$jazz.set` instead.
+   */
+  override fill(value: never, start?: never, end?: never): never {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.$jazz.set` instead.",
+    );
+  }
+  /**
+   * @deprecated Use `.toReversed` if you want a reversed copy, or `.$jazz.set` to mutate the CoList.
+   */
+  // @ts-expect-error
+  override reverse(value: never): never {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.toReversed` if you want a reversed copy, or `.$jazz.set` to mutate the CoList.",
+    );
+  }
+  /**
+   * @deprecated Use `.toSorted()` if you want a sorted copy, or `.$jazz.set` to mutate the CoList.
+   */
+  override sort(compareFn?: never): never {
+    throw new Error(
+      "Cannot mutate a CoList directly. Use `.toSorted` if you want a sorted copy, or `.$jazz.set` to mutate the CoList.",
+    );
+  }
+}
+
+/** @internal */
+type CoListItem<L> = L extends CoList<unknown> ? L[number] : never;
+
+export class CoListJazzApi<L extends CoList> extends CoValueJazzApi<L> {
+  constructor(
+    private coList: L,
+    private getRaw: () => RawCoList,
+  ) {
+    super(coList);
+  }
+
+  /**
+   * The ID of this `CoList`
+   * @category Content
+   */
+  get id(): ID<L> {
+    return this.raw.id;
+  }
+
+  /** @category Collaboration */
+  get owner(): Group {
+    return getCoValueOwner(this.coList);
+  }
+
+  set(index: number, value: CoFieldInit<CoListItem<L>>): void {
+    const itemDescriptor = this.schema[ItemsSym];
+    const rawValue = toRawItems([value], itemDescriptor, this.owner)[0]!;
+    if (rawValue === null && !itemDescriptor.optional) {
+      throw new Error(`Cannot set required reference ${index} to undefined`);
+    }
+    this.raw.replace(index, rawValue);
+  }
+
+  /**
+   * Appends new elements to the end of an array, and returns the new length of the array.
+   * @param items New elements to add to the array.
+   *
+   * @category Content
+   */
+  push(...items: CoFieldInit<CoListItem<L>>[]): number {
+    this.raw.appendItems(
+      toRawItems(items, this.schema[ItemsSym], this.owner),
+      undefined,
+      "private",
+    );
+
+    return this.raw.entries().length;
+  }
+
+  /**
+   * Inserts new elements at the start of an array, and returns the new length of the array.
+   * @param items Elements to insert at the start of the array.
+   *
+   * @category Content
+   */
+  unshift(...items: CoFieldInit<CoListItem<L>>[]): number {
+    for (const item of toRawItems(
+      items as CoFieldInit<CoListItem<L>>[],
+      this.schema[ItemsSym],
+      this.owner,
+    )) {
+      this.raw.prepend(item);
+    }
+
+    return this.raw.entries().length;
+  }
+
+  /**
+   * Removes the last element from an array and returns it.
+   * If the array is empty, undefined is returned and the array is not modified.
+   *
+   * @category Content
+   */
+  pop(): CoListItem<L> | undefined {
+    const last = this.coList[this.coList.length - 1];
+
+    this.raw.delete(this.coList.length - 1);
+
+    return last;
+  }
+
+  /**
+   * Removes the first element from an array and returns it.
+   * If the array is empty, undefined is returned and the array is not modified.
+   *
+   * @category Content
+   */
+  shift(): CoListItem<L> | undefined {
+    const first = this.coList[0];
+
+    this.raw.delete(0);
+
+    return first;
+  }
+
+  /**
+   * Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
+   * @param start The zero-based location in the array from which to start removing elements.
+   * @param deleteCount The number of elements to remove.
+   * @param items Elements to insert into the array in place of the deleted elements.
+   * @returns An array containing the elements that were deleted.
+   *
+   * @category Content
+   */
+  splice(
+    start: number,
+    deleteCount: number,
+    ...items: CoFieldInit<CoListItem<L>>[]
+  ): CoListItem<L>[] {
+    const deleted = this.coList.slice(start, start + deleteCount);
+
+    for (
+      let idxToDelete = start + deleteCount - 1;
+      idxToDelete >= start;
+      idxToDelete--
+    ) {
+      this.raw.delete(idxToDelete);
+    }
+
+    const rawItems = toRawItems(
+      items as CoListItem<L>[],
+      this.schema[ItemsSym],
+      this.owner,
+    );
+
+    // If there are no items to insert, return the deleted items
+    if (rawItems.length === 0) {
+      return deleted;
+    }
+
+    // Fast path for single item insertion
+    if (rawItems.length === 1) {
+      const item = rawItems[0];
+      if (item === undefined) return deleted;
+      if (start === 0) {
+        this.raw.prepend(item);
+      } else {
+        this.raw.append(item, Math.max(start - 1, 0));
+      }
+      return deleted;
+    }
+
+    // Handle multiple items
+    if (start === 0) {
+      // Iterate in reverse order without creating a new array
+      for (let i = rawItems.length - 1; i >= 0; i--) {
+        const item = rawItems[i];
+        if (item === undefined) continue;
+        this.raw.prepend(item);
+      }
+    } else {
+      let appendAfter = Math.max(start - 1, 0);
+      for (const item of rawItems) {
+        if (item === undefined) continue;
+        this.raw.append(item, appendAfter);
+        appendAfter++;
+      }
+    }
+
+    return deleted;
+  }
+
+  /**
+   * Removes the elements at the specified indices from the array.
+   * @param indices The indices of the elements to remove.
+   * @returns The removed elements.
+   *
+   * @category Content
+   */
+  remove(...indices: number[]): CoListItem<L>[];
+  /**
+   * Removes the elements matching the predicate from the array.
+   * @param predicate The predicate to match the elements to remove.
+   * @returns The removed elements.
+   *
+   * @category Content
+   */
+  remove(
+    predicate: (item: CoListItem<L>, index: number, coList: L) => boolean,
+  ): CoListItem<L>[];
+  remove(
+    ...args: (
+      | number
+      | ((item: CoListItem<L>, index: number, coList: L) => boolean)
+    )[]
+  ): CoListItem<L>[] {
+    const predicate = args[0] instanceof Function ? args[0] : undefined;
+    let indices: number[] = [];
+    if (predicate) {
+      for (let i = 0; i < this.coList.length; i++) {
+        if (predicate(this.coList[i], i, this.coList)) {
+          indices.push(i);
+        }
+      }
+    } else {
+      indices = (args as number[])
+        .filter((index) => index >= 0 && index < this.coList.length)
+        .sort((a, b) => a - b);
+    }
+    const deletedItems = indices.map((index) => this.coList[index]);
+    for (const index of indices.reverse()) {
+      this.raw.delete(index);
+    }
+    return deletedItems;
+  }
+
+  /**
+   * Retains only the elements matching the predicate from the array.
+   * @param predicate The predicate to match the elements to retain.
+   * @returns The removed elements.
+   *
+   * @category Content
+   */
+  retain(
+    predicate: (item: CoListItem<L>, index: number, coList: L) => boolean,
+  ): CoListItem<L>[] {
+    return this.remove((...args) => !predicate(...args));
+  }
+
+  /**
+   * Modify the `CoList` to match another list, where the changes are managed internally.
+   *
+   * Changes are detected using `Object.is` for non-collaborative values and `$jazz.id` for collaborative values.
+   *
+   * @param result - The resolved list of items. For collaborative values, both CoValues and JSON values are supported.
+   * @returns The modified CoList.
+   *
+   * @category Content
+   */
+  applyDiff(result: CoFieldInit<CoListItem<L>>[]): L {
+    const current = this.raw.asArray() as CoFieldInit<CoListItem<L>>[];
+    const comparator = isRefEncoded(this.schema[ItemsSym])
+      ? (aIdx: number, bIdx: number) => {
+          const oldCoValueId = (current[aIdx] as CoValue)?.$jazz?.id;
+          const newCoValueId = (result[bIdx] as CoValue)?.$jazz?.id;
+          const isSame =
+            !!oldCoValueId && !!newCoValueId && oldCoValueId === newCoValueId;
+          return isSame;
+        }
+      : undefined;
+
+    const patches = [...calcPatch(current, result, comparator)];
+    for (const [from, to, insert] of patches.reverse()) {
+      this.splice(from, to - from, ...insert);
+    }
+    return this.coList;
+  }
+
+  /**
+   * Given an already loaded `CoList`, ensure that items are loaded to the specified depth.
+   *
+   * Works like `CoList.load()`, but you don't need to pass the ID or the account to load as again.
+   *
+   * @category Subscription & Loading
+   */
+  ensureLoaded<L extends CoList, const R extends RefsToResolve<L>>(
+    this: CoListJazzApi<L>,
+    options: { resolve: RefsToResolveStrict<L, R> },
+  ): Promise<Resolved<L, R>> {
+    return ensureCoValueLoaded(this.coList, options);
+  }
+
+  /**
+   * Given an already loaded `CoList`, subscribe to updates to the `CoList` and ensure that items are loaded to the specified depth.
+   *
+   * Works like `CoList.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<L extends CoList, const R extends RefsToResolve<L> = true>(
+    this: CoListJazzApi<L>,
+    listener: (value: Resolved<L, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<L extends CoList, const R extends RefsToResolve<L> = true>(
+    this: CoListJazzApi<L>,
+    options: { resolve?: RefsToResolveStrict<L, R> },
+    listener: (value: Resolved<L, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<L extends CoList, const R extends RefsToResolve<L>>(
+    this: CoListJazzApi<L>,
+    ...args: SubscribeRestArgs<L, R>
+  ): () => void {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this.coList, options, listener);
+  }
+
   /**
    * Wait for the `CoList` to be uploaded to the other peers.
    *
    * @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 the items in the `CoList`
+   * @internal
+   */
+  getItemsDescriptor(): Schema | undefined {
+    return this.schema[ItemsSym];
+  }
+
+  /**
+   * If a `CoList`'s items are a `coField.ref(...)`, you can use `coList.$jazz.refs[i]` 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
+   * animals.$jazz.refs[0].id; // => ID<Animal>
+   * animals.$jazz.refs[0].value;
+   * // => Animal | null
+   * const animal = await animals.$jazz.refs[0].load();
+   * ```
+   *
+   * @category Content
+   **/
+  get refs(): {
+    [idx: number]: Exclude<CoListItem<L>, null> extends CoValue
+      ? Ref<Exclude<CoListItem<L>, null>>
+      : never;
+  } & {
+    length: number;
+    [Symbol.iterator](): IterableIterator<
+      Exclude<CoListItem<L>, null> extends CoValue
+        ? Ref<Exclude<CoListItem<L>, null>>
+        : never
+    >;
+  } {
+    return makeRefs<number>(
+      this.coList,
+      (idx) => this.raw.get(idx) as unknown as ID<CoValue>,
+      () => Array.from({ length: this.raw.entries().length }, (_, idx) => idx),
+      this.loadedAs,
+      (_idx) => this.schema[ItemsSym] as RefEncoded<CoValue>,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) as any;
+  }
+
+  /**
+   * Get the edits made to the CoList.
+   *
+   * @category Collaboration
+   */
+  getEdits(): {
+    [idx: number]: {
+      value?: CoListItem<L>;
+      ref?: CoListItem<L> extends CoValue ? Ref<CoListItem<L>> : never;
+      by: Account | null;
+      madeAt: Date;
+    };
+  } {
+    throw new Error("Not implemented");
+  }
+
+  /** @internal */
+  get raw(): RawCoList {
+    return this.getRaw();
+  }
+
+  /** @internal */
+  get schema(): {
+    [ItemsSym]: SchemaFor<CoListItem<L>> | any;
+  } {
+    return (this.coList.constructor as typeof CoList)._schema;
   }
 }
 
@@ -690,8 +885,8 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
 function toRawItems<Item>(
   items: Item[],
   itemDescriptor: Schema,
-  owner: Account | Group,
-) {
+  owner: Group,
+): JsonValue[] {
   let rawItems: JsonValue[] = [];
   if (itemDescriptor === "json") {
     rawItems = items as JsonValue[];
@@ -699,15 +894,17 @@ function toRawItems<Item>(
     rawItems = items?.map((e) => itemDescriptor.encoded.encode(e));
   } else if (isRefEncoded(itemDescriptor)) {
     rawItems = items?.map((value) => {
-      if (value == null) return null;
-      let refId = (value as unknown as CoValue).id;
+      if (value == null) {
+        return null;
+      }
+      let refId = (value as unknown as CoValue).$jazz?.id;
       if (!refId) {
         const coValue = instantiateRefEncodedWithInit(
           itemDescriptor,
           value,
           owner,
         );
-        refId = coValue.id;
+        refId = coValue.$jazz.id;
       }
       return refId;
     });
@@ -720,8 +917,8 @@ function toRawItems<Item>(
 const CoListProxyHandler: ProxyHandler<CoList> = {
   get(target, key, receiver) {
     if (typeof key === "string" && !isNaN(+key)) {
-      const itemDescriptor = target._schema[ItemsSym] as Schema;
-      const rawValue = target._raw.get(Number(key));
+      const itemDescriptor = target.$jazz.schema[ItemsSym] as Schema;
+      const rawValue = target.$jazz.raw.get(Number(key));
       if (itemDescriptor === "json") {
         return rawValue;
       } else if ("encoded" in itemDescriptor) {
@@ -734,7 +931,7 @@ const CoListProxyHandler: ProxyHandler<CoList> = {
           : accessChildByKey(target, rawValue as string, key);
       }
     } else if (key === "length") {
-      return target._raw.entries().length;
+      return target.$jazz.raw.entries().length;
     } else {
       return Reflect.get(target, key, receiver);
     }
@@ -747,31 +944,7 @@ const CoListProxyHandler: ProxyHandler<CoList> = {
       return true;
     }
     if (typeof key === "string" && !isNaN(+key)) {
-      const itemDescriptor = target._schema[ItemsSym] as Schema;
-      let rawValue;
-      if (itemDescriptor === "json") {
-        rawValue = value;
-      } else if ("encoded" in itemDescriptor) {
-        rawValue = itemDescriptor.encoded.encode(value);
-      } else if (isRefEncoded(itemDescriptor)) {
-        if (value === undefined) {
-          if (itemDescriptor.optional) {
-            rawValue = null;
-          } else {
-            throw new Error(
-              `Cannot set required reference ${key} to undefined`,
-            );
-          }
-        } else if (value?.id) {
-          rawValue = value.id;
-        } else {
-          throw new Error(
-            `Cannot set reference ${key} to a non-CoValue. Got ${value}`,
-          );
-        }
-      }
-      target._raw.replace(Number(key), rawValue);
-      return true;
+      throw Error("Cannot update a CoList directly. Use `$jazz.set` instead.");
     } else {
       return Reflect.set(target, key, value, receiver);
     }
@@ -793,7 +966,7 @@ const CoListProxyHandler: ProxyHandler<CoList> = {
   },
   has(target, key) {
     if (typeof key === "string" && !isNaN(+key)) {
-      return Number(key) < target._raw.entries().length;
+      return Number(key) < target.$jazz.raw.entries().length;
     } else {
       return Reflect.has(target, key);
     }