@evolu/common 7.4.1 → 8.0.0-next.1

package/src/Ref.ts

@@ -1,23 +1,29 @@
+/**
+ * Mutable reference to an immutable value.
+ *
+ * @module
+ */
+
 import type { Store } from "./Store.js";
 
 /**
- * `Ref` provides a simple API to hold and update a value, similar to a "ref" in
- * functional programming or React. It exposes methods to get, set, and modify
- * the current state.
+ * Mutable reference to an immutable value.
  *
- * Use a Ref instead of a variable when you want to pass state around as an
- * object or update it in a controlled way. If you need subscriptions, see
- * {@link Store}.
+ * `Ref` holds the current value and exposes explicit `get`, `set`, `update`,
+ * and `modify` operations. The reference is mutable, but the value inside it
+ * must be immutable and replaced with a new value rather than mutated in place.
+ * Storing a mutable value in `Ref` does not make sense, because callers could
+ * mutate that value directly and pass it around without `Ref`.
  *
- * Updating in a controlled way means all changes go through specific methods
- * (`set` or `modify`), making state updates predictable and easy to track.
+ * Use it when mutable ownership of a value needs to be passed around as a
+ * value. For reactive state with subscriptions, see {@link Store}.
  *
  * ### Example
  *
  * ```ts
  * const count = createRef(0);
  * count.set(1);
- * count.modify((n) => n + 1);
+ * count.update((n) => n + 1);
  * console.log(count.get()); // 2
  * ```
  *
@@ -30,29 +36,74 @@ import type { Store } from "./Store.js";
  * ```
  */
 export interface Ref<T> {
-  /** Returns the current state. */
+  /** Returns the current value. */
   readonly get: () => T;
 
-  /** Sets the state. */
-  readonly set: (state: T) => void;
+  /** Sets the current value. */
+  readonly set: (value: T) => void;
+
+  /** Sets the current value and returns the previous value. */
+  readonly getAndSet: (value: T) => T;
 
-  /** Modifies the state using an updater function. */
-  readonly modify: (updater: (current: T) => T) => void;
+  /** Sets the current value and returns it. */
+  readonly setAndGet: (value: T) => T;
+
+  /** Updates the current value. */
+  readonly update: (updater: (current: T) => T) => void;
+
+  /** Updates the current value and returns the previous value. */
+  readonly getAndUpdate: (updater: (current: T) => T) => T;
+
+  /** Updates the current value and returns it. */
+  readonly updateAndGet: (updater: (current: T) => T) => T;
+
+  /** Modifies the current value and returns a computed result. */
+  readonly modify: <R>(
+    updater: (current: T) => readonly [result: R, nextValue: T],
+  ) => R;
 }
 
-/** Creates a {@link Ref} with the given initial state. */
-export const createRef = <T>(initialState: T): Ref<T> => {
-  let currentState = initialState;
+/** Creates a {@link Ref} with the given initial immutable value. */
+export const createRef = <T>(initialValue: T): Ref<T> => {
+  let currentValue = initialValue;
 
   return {
-    get: () => currentState,
+    get: () => currentValue,
+
+    set: (value) => {
+      currentValue = value;
+    },
+
+    getAndSet: (value) => {
+      const previousValue = currentValue;
+      currentValue = value;
+      return previousValue;
+    },
+
+    setAndGet: (value) => {
+      currentValue = value;
+      return currentValue;
+    },
+
+    update: (updater) => {
+      currentValue = updater(currentValue);
+    },
+
+    getAndUpdate: (updater) => {
+      const previousValue = currentValue;
+      currentValue = updater(currentValue);
+      return previousValue;
+    },
 
-    set: (state) => {
-      currentState = state;
+    updateAndGet: (updater) => {
+      currentValue = updater(currentValue);
+      return currentValue;
     },
 
     modify: (updater) => {
-      currentState = updater(currentState);
+      const [result, nextValue] = updater(currentValue);
+      currentValue = nextValue;
+      return result;
     },
   };
 };

package/src/RefCount.ts

@@ -0,0 +1,170 @@
+/**
+ * Reference counting helpers.
+ *
+ * @module
+ */
+
+import { assert, assertNotDisposed } from "./Assert.js";
+import { identity } from "./Function.js";
+import { createLookupMap, type Lookup, type LookupOption } from "./Lookup.js";
+import { NonNegativeInt, PositiveInt, zeroNonNegativeInt } from "./Type.js";
+
+/**
+ * Reference count for one retained value.
+ *
+ * Decrementing below zero is a programmer error checked with {@link assert}.
+ */
+export interface RefCount extends Disposable {
+  /** Increments the count and returns the new count. */
+  readonly increment: () => PositiveInt;
+
+  /**
+   * Decrements the count and returns the new count.
+   *
+   * Decrementing below zero is a programmer error checked with {@link assert}.
+   */
+  readonly decrement: () => NonNegativeInt;
+
+  /** Returns the current count. */
+  readonly getCount: () => NonNegativeInt;
+
+  /** Disposes and invalidates the helper. Further method calls throw. */
+  readonly [Symbol.dispose]: () => void;
+}
+
+/** Creates {@link RefCount}. */
+export const createRefCount = (): RefCount => {
+  let count = zeroNonNegativeInt;
+  const stack = new DisposableStack();
+  stack.defer(() => {
+    count = zeroNonNegativeInt;
+  });
+  const moved = stack.move();
+
+  return {
+    increment: () => {
+      assertNotDisposed(moved);
+      const nextCount = PositiveInt.orThrow(count + 1);
+      count = nextCount;
+      return nextCount;
+    },
+
+    decrement: () => {
+      assertNotDisposed(moved);
+      assert(count > 0, "RefCount must not be decremented below zero.");
+      count = NonNegativeInt.orThrow(count - 1);
+      return count;
+    },
+
+    getCount: () => {
+      assertNotDisposed(moved);
+      return count;
+    },
+
+    [Symbol.dispose]: () => moved.dispose(),
+  };
+};
+
+/**
+ * Reference counts keyed by logical identity.
+ *
+ * By default, {@link createRefCountByKey} uses reference identity, the same as
+ * `Map` keys. Callers may instead provide a {@link Lookup lookup} so logical
+ * equality is based on a derived stable key. Decrementing a missing key is a
+ * programmer error checked with {@link assert}.
+ */
+export interface RefCountByKey<TKey> extends Disposable {
+  /** Increments key count and returns the new count. */
+  readonly increment: (key: TKey) => PositiveInt;
+
+  /**
+   * Decrements key count and returns the new count.
+   *
+   * Decrementing a missing key is a programmer error checked with
+   * {@link assert}.
+   */
+  readonly decrement: (key: TKey) => NonNegativeInt;
+
+  /** Gets current count for key. Returns `0` when the key is not tracked. */
+  readonly getCount: (key: TKey) => NonNegativeInt;
+
+  /** Returns `true` when the key is tracked with count greater than zero. */
+  readonly has: (key: TKey) => boolean;
+
+  /** Returns all currently tracked keys. */
+  readonly keys: () => ReadonlySet<TKey>;
+
+  /** Disposes and invalidates the helper. Further method calls throw. */
+  readonly [Symbol.dispose]: () => void;
+}
+
+/** Options for {@link createRefCountByKey}. */
+export interface CreateRefCountByKeyOptions<
+  TKey,
+  L = TKey,
+> extends LookupOption<TKey, L> {}
+
+/** Creates {@link RefCountByKey}. */
+export function createRefCountByKey<TKey = unknown>(): RefCountByKey<TKey>;
+export function createRefCountByKey<TKey, L>(
+  options: CreateRefCountByKeyOptions<TKey, L>,
+): RefCountByKey<TKey>;
+export function createRefCountByKey<TKey, L = TKey>({
+  lookup = identity as Lookup<TKey, L>,
+}: CreateRefCountByKeyOptions<TKey, L> = {}): RefCountByKey<TKey> {
+  const stack = new DisposableStack();
+
+  const refCountByKey = stack.adopt(
+    createLookupMap<TKey, RefCount, L>({ lookup }),
+    (refCountByKey) => {
+      for (const refCount of refCountByKey.values()) refCount[Symbol.dispose]();
+      refCountByKey.clear();
+    },
+  );
+
+  const moved = stack.move();
+
+  const getRefCount = (key: TKey): RefCount => {
+    let refCount = refCountByKey.get(key);
+    if (!refCount) {
+      refCount = createRefCount();
+      refCountByKey.set(key, refCount);
+    }
+    return refCount;
+  };
+
+  return {
+    increment: (key) => {
+      assertNotDisposed(moved);
+      return getRefCount(key).increment();
+    },
+
+    decrement: (key) => {
+      assertNotDisposed(moved);
+      const refCount = getRefCount(key);
+      const nextCount = refCount.decrement();
+      if (nextCount === 0) {
+        refCount[Symbol.dispose]();
+        refCountByKey.delete(key);
+      }
+      return nextCount;
+    },
+
+    getCount: (key) => {
+      assertNotDisposed(moved);
+      return refCountByKey.get(key)?.getCount() ?? zeroNonNegativeInt;
+    },
+
+    has: (key) => {
+      assertNotDisposed(moved);
+      return refCountByKey.has(key);
+    },
+
+    keys: () => {
+      assertNotDisposed(moved);
+      return new Set(refCountByKey.keys());
+    },
+
+    [Symbol.dispose]: () => moved.dispose(),
+  };
+}