@superutils/rx 0.1.1

package/dist/index.js

@@ -0,0 +1,636 @@
+// src/asPromise.ts
+import {
+  fallbackIfFails,
+  isError,
+  isFn,
+  isObj,
+  isPositiveNumber,
+  isSubjectLike
+} from "@superutils/core";
+import PromisE, {
+  TIMEOUT_MAX
+} from "@superutils/promise";
+
+// src/rxjs.ts
+import {
+  BehaviorSubject,
+  isObservable,
+  skip,
+  Subject,
+  Subscription
+} from "rxjs";
+
+// src/asPromise.ts
+var asPromise = (subject, expectedValue, timeoutOrOptions) => {
+  if (!isSubjectLike(subject) && !isObservable(subject))
+    return PromisE.reject(
+      new Error("subject must be an instance of BehaviorSubject")
+    );
+  let subscription;
+  const options = isObj(timeoutOrOptions) ? timeoutOrOptions : { timeout: timeoutOrOptions };
+  options.timeout = isPositiveNumber(options.timeout) ? options.timeout : TIMEOUT_MAX;
+  const promise = PromisE.timeout(
+    {
+      ...options,
+      onTimeout: async () => {
+        const { onTimeout, timeoutMsg } = options;
+        const msg = await fallbackIfFails(onTimeout, [], void 0);
+        return msg != null ? msg : isError(timeoutMsg) ? timeoutMsg : new Error(
+          timeoutMsg != null ? timeoutMsg : "request timed out before an expected value is received"
+        );
+      }
+    },
+    new PromisE((resolve) => {
+      subscription = subject.subscribe((value) => {
+        const shouldResolve = value === expectedValue || expectedValue === void 0 || isFn(expectedValue) && fallbackIfFails(expectedValue, [value], false);
+        shouldResolve && resolve(value);
+      });
+    })
+  );
+  promise.onFinalize.push(() => {
+    var _a;
+    (_a = subscription == null ? void 0 : subscription.unsubscribe) == null ? void 0 : _a.call(subscription);
+  });
+  return promise;
+};
+
+// src/copyRxSubject.ts
+import {
+  deferred,
+  fallbackIfFails as fallbackIfFails2,
+  isArr,
+  isFn as isFn4,
+  isPositiveNumber as isPositiveNumber2
+} from "@superutils/core";
+
+// src/isSubjectLike.ts
+import { isSubjectLike as _isSubjectLike } from "@superutils/core";
+var isSubjectLike2 = (x, withValue = false) => _isSubjectLike(x, withValue);
+var isSubjectLike_default = isSubjectLike2;
+
+// src/unsubscribeAll.ts
+import { isFn as isFn3 } from "@superutils/core";
+
+// src/isSubscriptionLike.ts
+import { isBool, isFn as isFn2 } from "@superutils/core";
+var isSubscriptionLike = (value, strict = false) => {
+  if (value instanceof Subscription) return true;
+  const sub = value;
+  return !strict && !!sub && isBool(sub.closed) && isFn2(sub.unsubscribe);
+};
+var isSubscriptionLike_default = isSubscriptionLike;
+
+// src/unsubscribeAll.ts
+var unsubscribeAll = (unsub = {}, onError) => {
+  if (!unsub) return;
+  try {
+    if (isFn3(unsub)) return unsub();
+    if (isSubscriptionLike_default(unsub)) return unsub.unsubscribe();
+    Object.values(unsub).forEach(
+      (value) => unsubscribeAll(value, onError)
+    );
+  } catch (err) {
+    onError == null ? void 0 : onError(err);
+  }
+};
+var unsubscribeAll_default = unsubscribeAll;
+
+// src/copyRxSubject.ts
+var IGNORE_UPDATE_SYMBOL = /* @__PURE__ */ Symbol("ignore-rx-update");
+function copyRxSubject(source$, copy$, valueModifier, options) {
+  var _a;
+  copy$ = isSubjectLike_default(copy$) ? copy$ : new BehaviorSubject(void 0);
+  options = {
+    ...copyRxSubject.defaults,
+    ...options != null ? options : {}
+  };
+  const sourceArr = isSubjectLike_default(source$) ? [source$] : isArr(source$) ? source$ : [source$];
+  const cache = new Map(
+    sourceArr.map((subject, i) => [
+      i,
+      isSubjectLike_default(subject) ? subject.value : subject
+      // fixed value provided
+    ])
+  );
+  const triggerChange = () => {
+    const currentValue = isArr(source$) ? [...cache.values()] : cache.get(0);
+    if (!isFn4(valueModifier)) return copy$.next(currentValue);
+    const modifiedValue = fallbackIfFails2(
+      valueModifier,
+      [currentValue, void 0, copy$],
+      (err) => {
+        var _a2;
+        fallbackIfFails2(
+          (_a2 = options.onError) == null ? void 0 : _a2.bind(options.thisArg),
+          [err],
+          void 0
+        );
+        return IGNORE_UPDATE_SYMBOL;
+      }
+    );
+    modifiedValue !== IGNORE_UPDATE_SYMBOL && copy$.next(modifiedValue);
+  };
+  const triggerChangeDeferred = isPositiveNumber2(options.delay) ? deferred(triggerChange, options.delay, options) : triggerChange;
+  const subscriptions = sourceArr.map((subject, i) => {
+    if (!isSubjectLike_default(subject) || subject.closed) return;
+    return (subject instanceof BehaviorSubject ? subject.pipe(
+      skip(1)
+      // skip initial value
+    ) : subject).subscribe((newValue) => {
+      cache.set(i, newValue);
+      triggerChangeDeferred();
+    });
+  }).filter(Boolean);
+  const unsubscribeOrg = (_a = copy$ == null ? void 0 : copy$.unsubscribe) == null ? void 0 : _a.bind(copy$);
+  copy$.unsubscribe = (...args) => {
+    unsubscribeOrg == null ? void 0 : unsubscribeOrg(...args);
+    unsubscribeAll(subscriptions);
+    cache.clear();
+  };
+  triggerChange();
+  return copy$;
+}
+copyRxSubject.defaults = {
+  delay: 0,
+  throttle: false
+};
+copyRxSubject.IGNORE_UPDATE_SYMBOL = IGNORE_UPDATE_SYMBOL;
+
+// src/data-storage/DataStorage.ts
+import {
+  deferred as deferred2,
+  fallbackIfFails as fallbackIfFails3,
+  filter,
+  find,
+  getEntries,
+  getKeys,
+  isArr as isArr2,
+  isFn as isFn5,
+  isMap,
+  isPositiveNumber as isPositiveNumber3,
+  isStr,
+  mapJoin,
+  search,
+  sort
+} from "@superutils/core";
+var forceUpdateCache$ = new Subject();
+var DataStorage = class {
+  /**
+   * A wrapper for reading and writing to LocalStorage (browser) or JSON files (NodeJS),
+   * providing a Map-like interface with advanced features like search, filtering, and sorting.
+   *
+   * #### Notes:
+   * - **Performance**: `DataStorage` is optimized for small to medium datasets.
+   *   - For datasets > 1MB, consider increasing the `delay` option to reduce write frequency.
+   *   - It is **NOT** recommended for datasets larger than 3MB due to synchronous serialization costs.
+   * - **RxJS Integration**: Built on RxJS for reactive data handling, though no prior RxJS knowledge is required.
+   * - **Storage Behavior**:
+   *   - If `name` is omitted, the instance operates in-memory only and data is not persisted to storage.
+   *   - If `cacheDisabled` is `true`, data is not kept in memory; every read/write operation accesses the underlying
+   * storage directly.
+   *
+   * @example
+   * #### Browser Usage
+   * ```javascript
+   * import { DataStorage } from '@superutils/rx'
+   * import fetch from '@superutils/fetch'
+   *
+   * const storage = new DataStorage('products')
+   * const { products } = await fetch('[DUMMYJSON-DOT-COM]/products')
+   * // save all items to storage
+   * storage.setAll(
+   *   new Map(products.map(p => [p.id, p])), // convert to Map
+   * )
+   *
+   * // print product with id `1`
+   * console.log(storage.get(1))
+   *
+   * // search for items
+   * const searchResult = storage.search({
+   *   query: { availabilityStatus: 'low' }
+   * })
+   * console.log(searchResult)
+   * ```
+   * @example
+   * #### NodeJS Usage
+   * ```javascript
+   * import { DataStorage } from '@superutils/rx'
+   * import fetch from '@superutils/fetch'
+   * import { LocalStorage } from 'node-localstorage'
+   *
+   * // Add localStorage alternative for NodeJS that reads and writes to JSON files.
+   * // This is not necessary for browsers.
+   * globalThis.localStorage = new LocalStorage('./data', 1e7)
+   *
+   * const storage = new DataStorage('products')
+   * const { products } = await fetch('[DUMMYJSON-DOT-COM]/products')
+   * // save all items to storage
+   * storage.setAll(
+   *   new Map(products.map(p => [p.id, p])), // convert to Map
+   * )
+   *
+   * // print product with id `1`
+   * console.log(storage.get(1))
+   *
+   * // search for items
+   * const searchResult = storage.search({
+   *   query: { availabilityStatus: 'low' }
+   * })
+   * console.log(searchResult)
+   * ```
+   *
+   * @example
+   * #### Advanced: `onChange` and RxJS subject
+   *
+   * Internally, `DataStorage` uses RxJS subject which is exposed as `subject` property.
+   * You can use this to subscribe to changes and do additional operations such as logging or sanitization etc.
+   *
+   * Alternatively, you can also set the `onChange` callback which is triggered whenever the subject changes and
+   * does not require maintaining a subscription or knowledge of RxJS subject.
+   *
+   * ```javascript
+   * import { DataStorage } from '@superutils/rx'
+   *
+   * const storage = new DataStorage('my-data')
+   * const sub = storage.subject.subscribe(data => {
+   *   // Write to the database whenever data changes
+   *   console.log('Saving to database...', data)
+   * })
+   * // unsubscribe from subject
+   * setTimeout(()=> sub.unsbuscribe(), 1000)
+   *
+   * // add an entry to storage
+   * storage.set('bob', { age: 99, id: 'bob', name: 'Bob' })
+   * ```
+   */
+  constructor(name, options) {
+    /** Debounce and throttle related options */
+    // readonly deferOptions
+    this.initialized = false;
+    this.subscriptions = {
+      subject: void 0,
+      forceUpdateCache: void 0
+    };
+    this.clear = () => {
+      this.setAll(/* @__PURE__ */ new Map(), true);
+      return this;
+    };
+    this.delete = (keys) => {
+      if (!isArr2(keys)) keys = [keys];
+      const data = this.getAll();
+      for (const k of keys) data.delete(k);
+      this.setAll(data, true);
+      return this;
+    };
+    this.find = (predicateOrOptions) => find(this.getAll(), predicateOrOptions);
+    this.filter = (predicate, limit, asArray, result) => filter(this.getAll(), predicate, limit, asArray, result);
+    this.get = (key) => this.getAll().get(key);
+    this.getAll = (forceRead = false) => {
+      var _a;
+      const wasInitialized = this.initialized;
+      if (!wasInitialized) this.init();
+      const readFromStorage = this.cacheDisabled || this.name && forceRead;
+      if (readFromStorage) {
+        const data = this.read();
+        const shouldTrigger = forceRead || !wasInitialized && !!data.size;
+        shouldTrigger && this.subject.next(data);
+        return data;
+      }
+      return (_a = this.subject) == null ? void 0 : _a.value;
+    };
+    this.has = (key) => this.getAll().has(key);
+    this.init = (initialValue) => {
+      var _a, _b;
+      if (this.initialized) return false;
+      this.initialized = true;
+      this.subject instanceof BehaviorSubject && this.subject.next(this.read());
+      unsubscribeAll_default(this.subscriptions);
+      if (!this.cacheDisabled) {
+        this.subscriptions.forceUpdateCache = forceUpdateCache$.subscribe(
+          (refresh) => {
+            const doRefresh = !this.name ? false : isArr2(refresh) ? refresh.includes(this.name) : isStr(refresh) ? refresh === this.name : refresh === true;
+            if (!doRefresh) return;
+            const newData = this.read();
+            this.subject.next(newData);
+          }
+        );
+      }
+      !((_b = (_a = this.subject) == null ? void 0 : _a.value) == null ? void 0 : _b.size) && isMap(initialValue) && !!(initialValue == null ? void 0 : initialValue.size) && this.setAll(initialValue);
+      const piped = this.subject.pipe(
+        skip(this.cacheDisabled || !!(initialValue == null ? void 0 : initialValue.size) ? 0 : 1)
+      );
+      let handleChange = (data) => {
+        if (!isMap(data)) return this.subject.next(/* @__PURE__ */ new Map());
+        this.write(data);
+        fallbackIfFails3(
+          async () => {
+            var _a2;
+            return await ((_a2 = this.onChange) == null ? void 0 : _a2.call(this, data));
+          },
+          [],
+          this.triggerOnError("onChange")
+        );
+      };
+      if (this.delay > 0)
+        handleChange = deferred2(handleChange, this.delay, this.delayOptions);
+      this.subscriptions.subject = piped.subscribe(handleChange);
+      return true;
+    };
+    this.keys = () => getKeys(this.getAll());
+    this.map = (callback) => this.toArray().map(
+      ([key, value], index, data) => callback(value, key, data, index)
+    );
+    this.read = () => {
+      var _a, _b;
+      const dataStr = (_b = (_a = this.storage) == null ? void 0 : _a.getItem(this.name)) != null ? _b : "[]";
+      const data = isFn5(this.parse) && fallbackIfFails3(
+        this.parse,
+        [dataStr],
+        this.triggerOnError("parse")
+      );
+      if (isMap(data)) return data;
+      return new Map(
+        fallbackIfFails3(
+          () => JSON.parse(dataStr),
+          [],
+          this.triggerOnError("parse-json")
+        )
+      );
+    };
+    this.search = (options) => search(this.getAll(), options);
+    this.set = (key, value) => {
+      this.setAll(/* @__PURE__ */ new Map([[key, value]]), false);
+      return this;
+    };
+    this.setAll = (data = /* @__PURE__ */ new Map(), replace = false) => {
+      if (!isMap(data)) return this;
+      data = replace ? data : mapJoin(this.getAll(), data);
+      this.subject.next(new Map(data));
+      return this;
+    };
+    this.sort = ((nameOrComparator, options) => {
+      const result = sort(
+        this.getAll(),
+        nameOrComparator,
+        options
+      );
+      (options == null ? void 0 : options.save) && this.setAll(result, true);
+      return result;
+    });
+    this.toArray = () => getEntries(this.getAll());
+    this.toJSON = (replacer, spacing = this.spaces, data = this.getAll()) => {
+      const arr = Array.from(data);
+      const str = fallbackIfFails3(
+        () => {
+          var _a;
+          return (_a = this.stringify) == null ? void 0 : _a.call(this, data);
+        },
+        [],
+        this.triggerOnError("stringify")
+      );
+      if (isStr(str)) return str;
+      return fallbackIfFails3(
+        () => JSON.stringify(arr, replacer, spacing),
+        [],
+        this.triggerOnError("stringify-json")
+      );
+    };
+    this.toString = (data) => this.toJSON(void 0, void 0, data);
+    this.triggerOnError = (type) => (err) => {
+      this.onError && fallbackIfFails3(this.onError, [err, type], "");
+    };
+    this.unsubscribe = () => unsubscribeAll_default(this.subscriptions);
+    this.values = () => [...this.getAll().values()];
+    this.write = (data) => {
+      try {
+        !this.initialized && this.init();
+        data != null ? data : data = this.subject.value;
+        if (!this.name || !this.storage || !isMap(data)) return false;
+        this.storage.setItem(this.name, this.toString(data));
+        return true;
+      } catch (err) {
+        this.triggerOnError("write")(err);
+        return false;
+      }
+    };
+    const {
+      cacheDisabled = false,
+      delay,
+      delayOptions,
+      initialValue,
+      onError,
+      onChange,
+      parse,
+      spaces,
+      storage,
+      stringify
+    } = options != null ? options : {};
+    this.delay = cacheDisabled ? 0 : delay === 0 || isPositiveNumber3(delay) ? delay : 300;
+    this.name = `${name != null ? name : ""}`.trim();
+    this.onError = onError;
+    this.onChange = onChange;
+    this.parse = parse;
+    this.storage = storage === null ? null : storage != null ? storage : fallbackIfFails3(
+      () => globalThis.localStorage,
+      [],
+      void 0
+    );
+    if (this.name && !this.storage)
+      throw new Error(
+        "options.storage: LocalStorage instance or equivalent required"
+      );
+    this.cacheDisabled = !!this.storage && cacheDisabled;
+    this.stringify = stringify;
+    this.spaces = spaces;
+    this.subject = this.cacheDisabled ? new Subject() : new BehaviorSubject(void 0);
+    this.delayOptions = delayOptions;
+    isMap(initialValue) && initialValue.size && this.init(initialValue);
+  }
+  get size() {
+    return this.getAll().size;
+  }
+};
+/**
+ * Trigger forced update of cached data from storage.
+ *
+ * @param name determines which storage instances to be updated.
+ * - name (`string` | `string[]`): update all instances with a specific name(s)
+ * - global (`true`): update all instances globally
+ *
+ * @example
+ * ```javascript
+ * import { DataStorage } from '@superutils/rx'
+ *
+ * // Update all DataStorage instances with specific name(s)
+ * const name = 'products'
+ * DataStorage.forceUpdateCache([name])
+ *
+ * // Update every single instance of DataStorage that uses storage (has a "name")
+ * DataStorage.forceUpdateCache(true)
+ * ```
+ */
+DataStorage.forceUpdateCache = (name) => {
+  forceUpdateCache$.next(name);
+};
+
+// src/IntervalSubject.ts
+var IntervalSubject = class extends BehaviorSubject {
+  constructor(autoStart, _delay = 1e3, initialValue = 0, incrementBy = 1) {
+    super(initialValue);
+    this.autoStart = autoStart;
+    this._delay = _delay;
+    this.initialValue = initialValue;
+    this.incrementBy = incrementBy;
+    this._running = false;
+    this.pause = () => {
+      clearInterval(this._intervalId);
+      this._running = false;
+      return this;
+    };
+    this.resume = () => this.start();
+    this.start = () => {
+      if (!this._running) {
+        this._running = true;
+        this._intervalId = setInterval(
+          () => this.next(this.value + this.incrementBy),
+          this._delay
+        );
+      }
+      return this;
+    };
+    this.stop = () => {
+      this.pause();
+      this.next(0);
+      return this;
+    };
+    this.autoStart && this.start();
+  }
+  get delay() {
+    return this._delay;
+  }
+  set delay(newDelay) {
+    if (!this._running) this._delay = newDelay;
+  }
+  get running() {
+    return this._running;
+  }
+};
+
+// src/IntervalRunner.ts
+import { fallbackIfFails as fallbackIfFails4, noop } from "@superutils/core";
+var IntervalRunner = class {
+  constructor(taskFn, taskArgs, intervalMs, sequential = true, preExecute = true) {
+    this.taskFn = taskFn;
+    this.taskArgs = taskArgs;
+    this.sequential = sequential;
+    this.preExecute = preExecute;
+    this.minIntervalMs = 1e3;
+    this.runCount = 0;
+    this.started = false;
+    this.clearInterval = () => {
+      this.sequential ? clearTimeout(this.idInterval) : clearInterval(this.idInterval);
+      this.idInterval = void 0;
+    };
+    this.executeTask = async (once = false) => {
+      var _a;
+      let err;
+      let result;
+      if (this.sequential || once) this.clearInterval();
+      try {
+        ++this.runCount;
+        await ((_a = this.onBeforeExec) == null ? void 0 : _a.call(this, this.runCount, once));
+        result = await this.taskFn.apply(void 0, this.taskArgs);
+        this.lastResult = result;
+      } catch (_err) {
+        err = _err;
+      }
+      fallbackIfFails4(
+        this.onResult,
+        [err != null ? err : null, result, this.runCount, once],
+        void 0
+      );
+      if (!once && this.sequential && this.intervalMs$.value > this.minIntervalMs) {
+        this.idInterval = setTimeout(
+          this.executeTask,
+          this.intervalMs$.value
+        );
+      }
+      return this.lastResult;
+    };
+    /** Execute the task function regardless of the interval runner state */
+    this.executeOnce = async () => await this.executeTask(true);
+    /** Check if interval is running*/
+    this.isStarted = () => this.started;
+    /**
+     * Restart interval
+     *
+     * @param resetRunCount (optional) whether to reset run count
+     *
+     * @returns {Boolean} indicates whether restart was successful
+     */
+    this.restart = (resetRunCount = false) => {
+      if (!this.onResult) return false;
+      this.stop(resetRunCount);
+      this.start(this.onResult, this.onBeforeExec);
+      return true;
+    };
+    /**
+     * @summary set `onResult` & `onBeforeExec` callbacks and start execution.
+     *
+     * If it's already running, the callbacks will be used on the next execution.
+     *
+     * In order to start using callbacks immediately, invoke the `intervalRunner.stop()` function first.
+     *
+     * @returns {Boolean} indicates whether starting interveral waa successful
+     */
+    this.start = (onResult, onBeforeExec) => {
+      if (!onResult) return false;
+      this.onResult = onResult;
+      this.onBeforeExec = onBeforeExec;
+      if (this.started) return false;
+      this.started = true;
+      let delayMs;
+      this.subscription = this.intervalMs$.subscribe((newDelayMs) => {
+        var _a;
+        if (delayMs === newDelayMs && newDelayMs !== void 0) return;
+        delayMs = Math.max((_a = newDelayMs != null ? newDelayMs : delayMs) != null ? _a : 0, this.minIntervalMs);
+        this.clearInterval();
+        const preExec = this.lastResult === void 0 && this.preExecute;
+        preExec && this.executeTask().catch(noop);
+        this.idInterval = !this.sequential ? setInterval(this.executeTask, delayMs) : !preExec ? setTimeout(this.executeTask, delayMs) : void 0;
+      });
+      return true;
+    };
+    /**
+     * Stop interval runner
+     *
+     * @param	resetRunCount	(optional) whether to reset the run counter
+     */
+    this.stop = (resetRunCount = false) => {
+      var _a, _b;
+      if (resetRunCount) this.runCount = 0;
+      this.started = false;
+      (_b = (_a = this.subscription) == null ? void 0 : _a.unsubscribe) == null ? void 0 : _b.call(_a);
+      this.clearInterval();
+      return this;
+    };
+    this.intervalMs$ = intervalMs instanceof BehaviorSubject ? intervalMs : new BehaviorSubject(intervalMs);
+  }
+};
+export {
+  BehaviorSubject,
+  DataStorage,
+  IGNORE_UPDATE_SYMBOL,
+  IntervalRunner,
+  IntervalSubject,
+  Subject,
+  Subscription,
+  asPromise,
+  copyRxSubject,
+  forceUpdateCache$,
+  isObservable,
+  isSubjectLike2 as isSubjectLike,
+  isSubscriptionLike,
+  skip,
+  unsubscribeAll
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+	"author": "Toufiqur Rahaman Chowdhury",
+	"description": "RxJS utilities and hooks for React applications.",
+	"dependencies": {
+		"@superutils/core": "^1.2.8",
+		"@superutils/promise": "^1.3.6",
+		"@types/react": "^18.0.0",
+		"react": ">=16.8.0",
+		"rxjs": "^7.8.2"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"keywords": [
+		"rxjs",
+		"utils",
+		"typescript",
+		"react",
+		"hooks"
+	],
+	"license": "MIT",
+	"name": "@superutils/rx",
+	"peerDependencies": {
+		"@superutils/core": "latest",
+		"@superutils/promise": "latest"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"_build": "tsc -p tsconfig.json",
+		"_watch": "tsc -p tsconfig.json --watch",
+		"build": "tsup --config ../../tsup.config.js",
+		"dev": "npm run build -- --watch",
+		"start": "npm run dev",
+		"test": "cd ../../ && npm run test rx"
+	},
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"type": "module",
+	"types": "./dist/index.d.ts",
+	"version": "0.1.1"
+}