@pistonite/pure 0.0.12 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pistonite/pure",
-    "version": "0.0.12",
+    "version": "0.0.14",
     "description": "Pure TypeScript libraries for my projects",
     "homepage": "https://github.com/Pistonite/pure",
     "bugs": {
@@ -9,7 +9,8 @@
     "license": "MIT",
     "author": "Pistonight <pistonknight@outlook.com>",
     "files": [
-        "src/**/*"
+        "src/**/*",
+        "!src/**/*.test.ts"
     ],
     "exports": {
         "./fs": "./src/fs/index.ts",
@@ -24,10 +25,11 @@
         "directory": "packages/pure"
     },
     "dependencies": {
+        "@types/file-saver": "^2.0.7",
         "denque": "2.1.0",
         "file-saver": "2.0.5"
     },
     "devDependencies": {
-        "@types/file-saver": "^2.0.7"
+        "vitest": "^2.1.8"
     }
 }

package/src/pref/dark.ts

@@ -50,12 +50,16 @@
  * @module
  */
 
+import { persist } from "../sync/persist.ts";
 import { injectStyle } from "./injectStyle.ts";
 
-const KEY = "Pure.Dark";
-
-let dark = false;
-const subscribers: ((dark: boolean) => void)[] = [];
+const dark = persist({
+    initial: false,
+    key: "Pure.Dark",
+    storage: localStorage,
+    serialize: (value) => (value ? "1" : ""),
+    deserialize: (value) => !!value,
+});
 
 /**
  * Returns if dark mode is prefered in the browser environment
@@ -96,20 +100,6 @@ export type DarkOptions = {
 export const initDark = (options: DarkOptions = {}): void => {
     let _dark = options.initial || prefersDarkMode();
 
-    if (options.persist) {
-        const value = localStorage.getItem(KEY);
-        if (value !== null) {
-            _dark = !!value;
-        }
-        addDarkSubscriber((dark: boolean) => {
-            localStorage.setItem(KEY, dark ? "1" : "");
-        });
-    } else {
-        localStorage.removeItem(KEY);
-    }
-
-    setDark(_dark);
-
     const selector = options.selector ?? ":root";
     if (selector) {
         // notify immediately to update the style initially
@@ -117,6 +107,12 @@ export const initDark = (options: DarkOptions = {}): void => {
             updateStyle(dark, selector);
         }, true /* notify */);
     }
+
+    if (options.persist) {
+        dark.init(_dark);
+    } else {
+        dark.disable();
+    }
 };
 
 /**
@@ -130,55 +126,33 @@ export const initDark = (options: DarkOptions = {}): void => {
  * subsequence `setDark` calls will still persist the value.
  */
 export const clearPersistedDarkPerference = (): void => {
-    localStorage.removeItem(KEY);
+    dark.clear();
 };
 
 /**
  * Gets the current value of dark mode
  */
-export const isDark = (): boolean => dark;
+export const isDark = (): boolean => dark.get();
 
 /**
  * Set the value of dark mode
  */
 export const setDark = (value: boolean): void => {
-    if (dark === value) {
-        return;
-    }
-    dark = value;
-    const len = subscribers.length;
-    for (let i = 0; i < len; i++) {
-        subscribers[i](dark);
-    }
+    dark.set(value);
 };
 /**
- * Add a subscriber to dark mode changes
+ * Add a subscriber to dark mode changes and return a function to remove the subscriber
  *
  * If `notifyImmediately` is `true`, the subscriber will be called immediately with the current value
  */
 export const addDarkSubscriber = (
     subscriber: (dark: boolean) => void,
     notifyImmediately?: boolean,
-): void => {
-    subscribers.push(subscriber);
-    if (notifyImmediately) {
-        subscriber(dark);
-    }
-};
-
-/**
- * Remove a subscriber from dark mode changes
- */
-export const removeDarkSubscriber = (
-    subscriber: (dark: boolean) => void,
-): void => {
-    const index = subscribers.indexOf(subscriber);
-    if (index >= 0) {
-        subscribers.splice(index, 1);
-    }
+): (() => void) => {
+    return dark.subscribe(subscriber, notifyImmediately);
 };
 
 const updateStyle = (dark: boolean, selector: string) => {
     const text = `${selector} { color-scheme: ${dark ? "dark" : "light"}; }`;
-    injectStyle(KEY, text);
+    injectStyle("pure-pref-dark", text);
 };

package/src/pref/locale.ts

@@ -53,12 +53,20 @@
  * @module
  */
 
-const KEY = "Pure.Locale";
+import { persist } from "../sync/persist.ts";
 
 let supportedLocales: readonly string[] = [];
-let locale: string = "";
 let defaultLocale: string = "";
-const subscribers: ((locale: string) => void)[] = [];
+const locale = persist<string>({
+    initial: "",
+    key: "Pure.Locale",
+    storage: localStorage,
+    serialize: (value) => value,
+    deserialize: (value) => {
+        const supported = convertToSupportedLocale(value);
+        return supported || null;
+    },
+});
 
 /**
  * Use browser API to guess user's preferred locale
@@ -120,21 +128,10 @@ export const initLocale = <TLocale extends string>(
     }
     defaultLocale = options.default;
     if (options.persist) {
-        const value = localStorage.getItem(KEY);
-        if (value !== null) {
-            const supported = convertToSupportedLocale(value);
-            if (supported) {
-                _locale = supported;
-            }
-        }
-        addLocaleSubscriber((locale: string) => {
-            localStorage.setItem(KEY, locale);
-        });
+        locale.init(_locale);
     } else {
-        localStorage.removeItem(KEY);
+        locale.disable();
     }
-
-    setLocale(_locale);
 };
 
 /**
@@ -149,13 +146,11 @@ export const initLocale = <TLocale extends string>(
  * subsequence `setLocale` calls will still persist the value.
  */
 export const clearPersistedLocalePreference = (): void => {
-    localStorage.removeItem(KEY);
+    locale.clear();
 };
 
 /** Get the current selected locale */
-export const getLocale = (): string => {
-    return locale;
-};
+export const getLocale = (): string => locale.get();
 
 /** Get the default locale when initialized */
 export const getDefaultLocale = (): string => {
@@ -172,14 +167,7 @@ export const setLocale = (newLocale: string): boolean => {
     if (!supported) {
         return false;
     }
-    if (supported === locale) {
-        return true;
-    }
-    locale = supported;
-    const len = subscribers.length;
-    for (let i = 0; i < len; i++) {
-        subscribers[i](locale);
-    }
+    locale.set(supported);
     return true;
 };
 
@@ -235,28 +223,16 @@ export const convertToSupportedLocaleOrDefault = (
 };
 
 /**
- * Add a subscriber to be notified when the locale changes
+ * Add a subscriber to be notified when the locale changes.
+ * Returns a function to remove the subscriber
  *
  * If `notifyImmediately` is `true`, the subscriber will be called immediately with the current locale
  */
 export const addLocaleSubscriber = (
     fn: (locale: string) => void,
     notifyImmediately?: boolean,
-): void => {
-    subscribers.push(fn);
-    if (notifyImmediately) {
-        fn(locale);
-    }
-};
-
-/**
- * Remove a subscriber from locale changes
- */
-export const removeLocaleSubscriber = (fn: (locale: string) => void): void => {
-    const index = subscribers.indexOf(fn);
-    if (index !== -1) {
-        subscribers.splice(index, 1);
-    }
+): (() => void) => {
+    return locale.subscribe(fn, notifyImmediately);
 };
 
 /**

package/src/sync/batch.ts

@@ -0,0 +1,233 @@
+import { makePromise, type AwaitRet } from "./util.ts";
+
+/**
+ * An async event wrapper that allows multiple calls in an interval
+ * to be batched together, and only call the underlying function once.
+ *
+ * Optionally, the output can be unbatched to match the inputs.
+ *
+ * ## Example
+ * The API is a lot like `debounce`, but with an additional `batch` function
+ * and an optional `unbatch` function.
+ * ```typescript
+ * import { batch } from "@pistonite/pure/sync";
+ *
+ * const execute = batch({
+ *     fn: (n: number) => {
+ *         console.log(n);
+ *     },
+ *     interval: 100,
+ *     // batch receives all the inputs and returns a single input
+ *     // here we just sums the inputs
+ *     batch: (args: [number][]): [number] => [args.reduce((acc, [n]) => acc + n, 0)],
+ * });
+ *
+ * await execute(1); // logs 1 immediately
+ * const p1 = execute(2); // will be resolved at 100ms
+ * const p2 = execute(3); // will be resolved at 100ms
+ * await Promise.all([p1, p2]); // logs 5 after 100ms
+ * ```
+ *
+ * ## Unbatching
+ * The optional `unbatch` function allows the output to be unbatched,
+ * so the promises are resolved as if the underlying function is called
+ * directly.
+ *
+ * Note that unbatching is usually slow and not required.
+ *
+ * ```typescript
+ * import { batch } from "@pistonite/pure/sync";
+ *
+ * type Message = {
+ *     id: number;
+ *     payload: string;
+ * }
+ *
+ * const execute = batch({
+ *     fn: (messages: Message[]): Message[] => {
+ *         console.log(messages.length);
+ *         return messages.map((m) => ({
+ *             id: m.id,
+ *             payload: m.payload + "out",
+ *         }));
+ *     },
+ *     batch: (args: [Message[]][]): [Message[]] => {
+ *         const out: Message[] = [];
+ *         for (const [messages] of args) {
+ *             out.push(...messages);
+ *         }
+ *         return [out];
+ *     },
+ *     unbatch: (inputs: [Message[]][], output: Message[]): Message[][] => {
+ *         // not efficient, but just for demonstration
+ *         const idToOutput = new Map();
+ *         for (const o of output) {
+ *             idToOutput.set(o.id, o);
+ *         }
+ *         return inputs.map(([messages]) => {
+ *             return messages.map(({id}) => {
+ *                 return idToOutput.get(m.id)!;
+ *             });
+ *         });
+ *     },
+ *     interval: 100,
+ * });
+ *
+ * const r1 = await execute([{id: 1, payload: "a"}]); // logs 1 immediately
+ * // r1 is [ {id: 1, payload: "aout"} ]
+ *
+ * const p1 = execute([{id: 2, payload: "b"}]); // will be resolved at 100ms
+ * const p2 = execute([{id: 3, payload: "c"}]); // will be resolved at 100ms
+ *
+ * const r2 = await p2; // 2 is logged
+ * // r1 is [ {id: 2, payload: "bout"} ]
+ * const r3 = await p3; // nothing is logged, as it's already resolved
+ * // r2 is [ {id: 3, payload: "cout"} ]
+ *
+ * ```
+ *
+ */
+export function batch<TFn extends (...args: any[]) => any>({
+    fn,
+    batch,
+    unbatch,
+    interval,
+    disregardExecutionTime,
+}: BatchConstructor<TFn>) {
+    const impl = new BatchImpl(
+        fn,
+        batch,
+        unbatch,
+        interval,
+        !!disregardExecutionTime,
+    );
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
+/**
+ * Options to construct a  `batch` function
+ */
+export type BatchConstructor<TFn extends (...args: any[]) => any> = {
+    /** Function to be wrapped */
+    fn: TFn;
+    /** Function to batch the inputs across multiple calls */
+    batch: (args: Parameters<TFn>[]) => Parameters<TFn>;
+
+    /**
+     * If provided, unbatch the output according to the inputs,
+     * so each call receives its own output.
+     *
+     * By default, each input will receive the same output from the batched call
+     */
+    unbatch?: (
+        inputs: Parameters<TFn>[],
+        output: AwaitRet<TFn>,
+    ) => AwaitRet<TFn>[];
+
+    /**
+     * Interval between each batched call
+     */
+    interval: number;
+
+    /** See `debounce` for more information */
+    disregardExecutionTime?: boolean;
+};
+
+class BatchImpl<TFn extends (...args: any[]) => any> {
+    private idle: boolean;
+    private scheduled: {
+        input: Parameters<TFn>;
+        promise: Promise<AwaitRet<TFn>>;
+        resolve: (value: AwaitRet<TFn>) => void;
+        reject: (error: unknown) => void;
+    }[];
+
+    constructor(
+        private fn: TFn,
+        private batch: (inputs: Parameters<TFn>[]) => Parameters<TFn>,
+        private unbatch:
+            | ((
+                  input: Parameters<TFn>[],
+                  output: AwaitRet<TFn>,
+              ) => AwaitRet<TFn>[])
+            | undefined,
+        private interval: number,
+        private disregardExecutionTime: boolean,
+    ) {
+        this.idle = true;
+        this.scheduled = [];
+    }
+
+    public invoke(...args: Parameters<TFn>): Promise<AwaitRet<TFn>> {
+        if (this.idle) {
+            this.idle = false;
+            return this.execute(...args);
+        }
+        const { promise, reject, resolve } = makePromise<AwaitRet<TFn>>();
+        this.scheduled.push({
+            input: args,
+            promise,
+            resolve,
+            reject,
+        });
+
+        return promise;
+    }
+
+    private async scheduleNext() {
+        const next = this.scheduled;
+        if (next.length) {
+            this.scheduled = [];
+            const batch = this.batch;
+            const inputs = next.map(({ input }) => input);
+            const input = next.length > 1 ? batch(inputs) : inputs[0];
+            try {
+                const output = await this.execute(...input);
+                const unbatch = this.unbatch;
+                if (unbatch && inputs.length > 1) {
+                    const outputs = unbatch(inputs, output);
+                    for (let i = 0; i < next.length; i++) {
+                        const { resolve } = next[i];
+                        resolve(outputs[i]);
+                    }
+                } else {
+                    for (let i = 0; i < next.length; i++) {
+                        const { resolve } = next[i];
+                        resolve(output);
+                    }
+                }
+            } catch (e) {
+                for (let i = 0; i < next.length; i++) {
+                    const { reject } = next[i];
+                    reject(e);
+                }
+            }
+            return;
+        }
+        this.idle = true;
+    }
+
+    private async execute(...args: Parameters<TFn>): Promise<AwaitRet<TFn>> {
+        const fn = this.fn;
+        let done = this.disregardExecutionTime;
+        setTimeout(() => {
+            if (done) {
+                this.scheduleNext();
+            } else {
+                done = true;
+            }
+        }, this.interval);
+        try {
+            return await fn(...args);
+        } finally {
+            if (!this.disregardExecutionTime) {
+                if (done) {
+                    // interval already passed, we need to call it
+                    this.scheduleNext();
+                } else {
+                    done = true;
+                }
+            }
+        }
+    }
+}

package/src/sync/cell.ts

@@ -0,0 +1,60 @@
+/**
+ * Create a light weight storage wrapper around a value
+ * that can be subscribed to for changes
+ */
+export function cell<T>({ initial }: CellConstructor<T>): Cell<T> {
+    return new CellImpl(initial);
+}
+
+export type CellConstructor<T> = {
+    /** Initial value */
+    initial: T;
+};
+
+export type Cell<T> = {
+    get(): T;
+    set(value: T): void;
+    subscribe(
+        callback: (value: T) => void,
+        notifyImmediately?: boolean,
+    ): () => void;
+};
+
+class CellImpl<T> implements Cell<T> {
+    private subscribers: ((value: T) => void)[] = [];
+
+    constructor(private value: T) {}
+
+    public get(): T {
+        return this.value;
+    }
+
+    public set(value: T): void {
+        if (this.value === value) {
+            return;
+        }
+        this.value = value;
+        const len = this.subscribers.length;
+        for (let i = 0; i < len; i++) {
+            const callback = this.subscribers[i];
+            callback(value);
+        }
+    }
+
+    public subscribe(
+        callback: (value: T) => void,
+        notifyImmediately?: boolean,
+    ): () => void {
+        this.subscribers.push(callback);
+        const unsubscribe = () => {
+            const index = this.subscribers.indexOf(callback);
+            if (index >= 0) {
+                this.subscribers.splice(index, 1);
+            }
+        };
+        if (notifyImmediately) {
+            callback(this.value);
+        }
+        return unsubscribe;
+    }
+}