@ibodr/store 0.2.5 → 0.2.7

package/dist/index.d.ts

@@ -104,6 +104,36 @@ declare class AtomMap<K, V> implements Map<K, V> {
      * ```
      */
     set(key: K, value: V): this;
+    /**
+     * Gets the value associated with a key, inserting `defaultValue` first if the key doesn't exist.
+     * This method is reactive and will cause reactive contexts to update when the value changes.
+     *
+     * @param key - The key to retrieve the value for
+     * @param defaultValue - The value to insert if the key doesn't exist
+     * @returns The existing value, or `defaultValue` if the key was missing
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * console.log(map.getOrInsert('count', 0)) // 0, and 'count' is now set
+     * console.log(map.getOrInsert('count', 10)) // 0
+     * ```
+     */
+    getOrInsert(key: K, defaultValue: V): V;
+    /**
+     * Gets the value associated with a key, inserting the result of `callback` first if the key
+     * doesn't exist. The callback only runs when the key is missing.
+     * This method is reactive and will cause reactive contexts to update when the value changes.
+     *
+     * @param key - The key to retrieve the value for
+     * @param callback - Called with the key to produce the value to insert
+     * @returns The existing value, or the newly computed value if the key was missing
+     * @example
+     * ```ts
+     * const map = new AtomMap<string, string[]>('myMap')
+     * map.getOrInsertComputed('tags', () => []).push('new')
+     * ```
+     */
+    getOrInsertComputed(key: K, callback: (key: K) => V): V;
     /**
      * Updates an existing value using an updater function.
      *
@@ -555,6 +585,10 @@ declare function squashRecordDiffs<T extends UnknownRecord>(diffs: RecordsDiff<T
  * - Updated records: Chain updates together, preserving the original 'from' state
  * - Removed records: If the record was added in this sequence, cancel both operations
  *
+ * The target's `updated` tuples are mutated in place, so the target must own them: start from
+ * `createEmptyRecordsDiff()` (or a diff built by earlier squashes into it) rather than a diff whose
+ * tuples are shared with another holder.
+ *
  * @param target - The diff to modify in-place (will be mutated)
  * @param diffs - Array of diffs to apply to the target
  * @example
@@ -581,7 +615,7 @@ declare function squashRecordDiffs<T extends UnknownRecord>(diffs: RecordsDiff<T
  *
  * @internal
  */
-declare function squashRecordDiffsMutable<T extends UnknownRecord>(target: RecordsDiff<T>, diffs: RecordsDiff<T>[]): void;
+declare function squashRecordDiffsMutable<T extends UnknownRecord>(target: RecordsDiff<T>, diffs: RecordsDiff<T>[], fromIndex?: number): void;
 
 /**
  * Defines the scope of the record
@@ -1419,6 +1453,7 @@ declare class StoreSchema<R extends UnknownRecord, P = unknown> {
      * @public
      */
     getMigrationsSince(persistedSchema: SerializedSchema): Result<Migration[], string>;
+    private computeMigrationsSince;
     /**
      * Migrates a single persisted record to match the current schema version.
      *
@@ -1748,6 +1783,7 @@ declare class StoreSideEffects<R extends UnknownRecord> {
     private _afterDeleteHandlers;
     private _operationCompleteHandlers;
     private _isEnabled;
+    private addHandler;
     /**
      * Checks whether side effects are currently enabled.
      * When disabled, all side effect handlers are bypassed.
@@ -2423,7 +2459,7 @@ declare class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
      */
     private historyReactor;
     /**
-     * Function to dispose of any in-flight timeouts.
+     * Cancels the history flush scheduled for the next frame, if any.
      *
      * @internal
      */
@@ -2959,17 +2995,19 @@ declare class StoreQueries<R extends UnknownRecord> {
      * have been added, updated, or removed.
      *
      * @param typeName - The type name to filter the history by
-     * @returns A computed value containing the current epoch and diffs of changes for the specified type
+     * @returns A computed value containing a change counter and diffs of changes for the specified type
      *
      * @example
      * ```ts
      * // Track changes to book records only
      * const bookHistory = store.query.filterHistory('book')
      *
-     * // React to book changes
-     * react('book-changes', () => {
-     *   const currentEpoch = bookHistory.get()
-     *   console.log('Books updated at epoch:', currentEpoch)
+     * // Log the books added since the last run
+     * react('book-changes', (lastReactedEpoch) => {
+     *   const diffs = bookHistory.getDiffSince(lastReactedEpoch)
+     *   // no diffs to give, e.g. on the first run: rebuild anything derived from scratch
+     *   if (diffs === RESET_VALUE) return
+     *   for (const diff of diffs) console.log('Added:', Object.keys(diff.added))
      * })
      * ```
      *