@evolu/common 5.4.8 → 6.0.0

package/src/Store.ts

@@ -1,42 +1,85 @@
-import * as Effect from "effect/Effect";
+/**
+ * A mutable reference for managing state with change notifications
+ *
+ * @module
+ */
+import { Eq, eqStrict } from "./Eq.js";
+import { Ref } from "./Ref.js";
 
-export type Listener = () => void;
+/**
+ * A store for managing state with change notifications. Extends {@link Ref} with
+ * subscriptions. Provides methods to get, set, and modify state, and to notify
+ * listeners when the state changes.
+ */
+export interface Store<T> extends Ref<T> {
+  /**
+   * Registers a listener to be called on state changes and returns a function
+   * to unsubscribe.
+   */
+  readonly subscribe: StoreSubscribe;
 
-export type Unsubscribe = () => void;
+  /** Returns the current state of the store. */
+  readonly get: () => T;
 
-export interface Store<T> {
-  // No Effect API because of React useSyncExternalStore
-  readonly subscribe: (listener: Listener) => Unsubscribe;
-  readonly getState: () => T;
+  /**
+   * Updates the store's state and notifies all subscribed listeners if the new
+   * state differs from the current one.
+   */
+  readonly set: (state: T) => void;
 
-  // Effect API because it's a side-effect.
-  readonly setState: (state: T) => Effect.Effect<void>;
+  /**
+   * Modifies the store's state by applying a callback function to the current
+   * state and notifies listeners if the state changes.
+   */
+  readonly modify: (updater: (current: T) => T) => void;
 }
 
-export const makeStore = <T>(initialState: T): Effect.Effect<Store<T>> =>
-  Effect.sync(() => {
-    const listeners = new Set<Listener>();
-    let currentState = initialState;
-
-    const store: Store<T> = {
-      subscribe(listener) {
-        listeners.add(listener);
-        return () => {
-          listeners.delete(listener);
-        };
-      },
-
-      getState() {
-        return currentState;
-      },
-
-      setState: (state) =>
-        Effect.sync(() => {
-          if (state === currentState) return;
-          currentState = state;
-          listeners.forEach((listener) => listener());
-        }),
-    };
-
-    return store;
-  });
+/** Registers a listener for state changes, returning an unsubscribe function. */
+export type StoreSubscribe = (listener: StoreListener) => StoreUnsubscribe;
+
+/** A callback invoked whenever the store's state updates. */
+export type StoreListener = () => void;
+
+/** A function to remove a previously added listener. */
+export type StoreUnsubscribe = () => void;
+
+/**
+ * Creates a store with the given initial state. The store encapsulates its
+ * state, which can be read with `get` and updated with `set` or `modify`. All
+ * changes are broadcast to subscribers.
+ *
+ * By default, state changes are detected using `===` (shallow equality). You
+ * can provide a custom equality function as the second argument.
+ */
+export const createStore = <T>(
+  initialState: T,
+  eq: Eq<T> = eqStrict,
+): Store<T> => {
+  const listeners = new Set<StoreListener>();
+  let currentState = initialState;
+
+  const updateState = (newState: T) => {
+    if (eq(newState, currentState)) return;
+    currentState = newState;
+    listeners.forEach((listener) => {
+      listener();
+    });
+  };
+
+  return {
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    get: () => currentState,
+
+    set: (state) => {
+      updateState(state);
+    },
+
+    modify: (updater) => {
+      updateState(updater(currentState));
+    },
+  };
+};

package/src/String.ts

@@ -0,0 +1,10 @@
+export const safelyStringifyUnknownValue = (value: unknown): string => {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return `"${value}"`;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return globalThis.String(value);
+  }
+};

package/src/Time.ts

@@ -0,0 +1,36 @@
+/**
+ * ⏳
+ *
+ * @module
+ */
+
+/** Retrieves the current time in milliseconds, similar to `Date.now()`. */
+export interface Time {
+  readonly now: () => number;
+}
+
+export interface TimeDep {
+  readonly time: Time;
+}
+
+/** Creates a {@link Time} using Date.now(). */
+export const createTime = (): Time => ({
+  now: () => Date.now(),
+});
+
+/**
+ * Creates a {@link Time} that returns a monotonically increasing number based on
+ * a queueMicrotask.
+ */
+export const createTestTime = (): Time => {
+  let now = 0;
+  return {
+    now: () => {
+      const current = now;
+      queueMicrotask(() => {
+        now++;
+      });
+      return current;
+    },
+  };
+};