@pistonite/pure 0.26.2 → 0.26.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pistonite/pure",
-  "version": "0.26.2",
+  "version": "0.26.4",
   "type": "module",
   "description": "Pure TypeScript libraries for my projects",
   "homepage": "https://github.com/Pistonite/pure",
@@ -26,11 +26,11 @@
     "url": "git+https://github.com/Pistonite/pure.git",
     "directory": "packages/pure"
   },
-  "dependencies": {
-    "denque": "2.1.0"
-  },
   "devDependencies": {
-    "vitest": "^3.1.1",
-    "mono-dev": "0.1.1"
+    "vitest": "^3.2.4",
+    "mono-dev": "0.2.2"
+  },
+  "dependencies": {
+    "denque": "^2.1.0"
   }
 }

package/src/log/index.ts

@@ -1,56 +1,154 @@
 /**
  * Client side log util
  *
+ * This is rather simple logging stuff with the primary focus
+ * being easy to debug.
+ *
+ * Use {@link logger} to create a logger with a name and a color,
+ * then use one of the {@link LoggerFactory} methods to setup the logging level.
+ *
+ * There are 3 levels of logging:
+ * 1. (Default) Warnings and Errors only
+ * 2. Also log info messages
+ * 3. Also log debug messages.
+ *
+ * Each logger can turn on info and debug logging separately, or it can
+ * be turned on at the global level for debugging.
+ *
+ * You can also turn off each logger individually or at global level for debugging.
+ *
+ * Due to the nature of JS, all logging calls, even when turned off, will incur
+ * some small runtime overhead. While we could remove debug calls
+ * for release build, that's currently not done (and it would require
+ * bundler to inline the call to remove the call completely, which might
+ * not be the case)
+ *
  * @module
  */
 
-import Denque from "denque";
 import { errstr } from "../result/index.ts";
 
-const LIMIT = 500;
+export const LogLevel = {
+    Off: 0,
+    High: 1,
+    Info: 2,
+    Debug: 3,
+} as const;
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
-/** Global log queue */
-const LogQueue = new Denque<string>();
-function pushLog(msg: string) {
-    if (LogQueue.length > LIMIT) {
-        LogQueue.shift();
-    }
-    LogQueue.push(`[${new Date().toISOString()}]${msg}`);
-}
+let globalLevel: LogLevel = LogLevel.High;
+/**
+ * Suppress ALL logging.
+ *
+ * This overrides logger-level settings
+ */
+export const globalLogOff = () => (globalLevel = 0);
+/**
+ * Enable +info logging for ALL loggers
+ *
+ * This overrides logger-level settings
+ */
+export const globalLogInfo = () => (globalLevel = 2);
+/**
+ * Enable +debug logging for ALL loggers
+ *
+ * This overrides logger-level settings
+ */
+export const globalLogDebug = () => (globalLevel = 3);
 
-/** Get the current log */
-export function getLogLines(): string[] {
-    return LogQueue.toArray();
-}
+/** Create a logger creator. Use the factory methods to finish making the logger */
+export const logger = (name: string, color?: string): LoggerFactory => {
+    return {
+        default: () => new LoggerImpl(name, color, LogLevel.High),
+        debug: () => new LoggerImpl(name, color, LogLevel.Debug),
+        info: () => new LoggerImpl(name, color, LogLevel.Info),
+        off: () => new LoggerImpl(name, color, LogLevel.Off),
+    };
+};
+
+export type LoggerFactory = {
+    /** Standard important logger (warning and errors) */
+    default(): Logger;
+    /** Enable +info +debug logging for this logger */
+    debug(): Logger;
+    /** Enable +info logging for this logger */
+    info(): Logger;
+    /** Stop all logging, including warn and error */
+    off(): Logger;
+};
+
+export type Logger = {
+    /** Log a debug message */
+    debug(obj: unknown): void;
+    /** Log an info message */
+    info(obj: unknown): void;
+    /** Log a warning message */
+    warn(obj: unknown): void;
+    /** Log an error message */
+    error(obj: unknown): void;
+};
 
-/** A general-purpose client side logger */
-export class Logger {
-    /** The prefix of the logger */
-    private prefix: string;
+class LoggerImpl implements Logger {
+    name: string;
+    color: string | undefined;
+    level: LogLevel;
 
-    constructor(prefix: string) {
-        this.prefix = prefix;
+    constructor(name: string, color: string | undefined, level: LogLevel) {
+        this.name = name;
+        this.color =
+            "padding:0 3x;color:white" + (color ? `;background:${color}` : "");
+        this.level = level;
     }
 
-    /** Log an info message */
-    public info(msg: string) {
-        const msgWithPrefix = `[${this.prefix}] ${msg}`;
-        self.console.info(msgWithPrefix);
-        pushLog(msgWithPrefix);
+    debug(obj: unknown) {
+        if (globalLevel !== LogLevel.Debug && this.level !== LogLevel.Debug) {
+            return;
+        }
+        console.log(
+            `%cDEBUG%c${this.name}%c ${obj}`,
+            "background:gray;color:white;padding:0 3px",
+            this.color,
+            "color:inherit;background:inherit",
+        );
     }
 
-    /** Log a warning message */
-    public warn(msg: string) {
-        const msgWithPrefix = `[${this.prefix}] ${msg}`;
-        self.console.warn(msgWithPrefix);
-        pushLog(msgWithPrefix);
+    info(obj: unknown) {
+        if (globalLevel < LogLevel.Info && this.level < LogLevel.Info) {
+            return;
+        }
+        console.log(
+            `%cINFO%c${this.name}%c ${obj}`,
+            "background:green;color:white;padding:0 3px",
+            this.color,
+            "color:inherit;background:inherit",
+        );
     }
 
-    /** Log an error message */
-    public error(msg: unknown) {
-        const msgWithPrefix = `[${this.prefix}] ${errstr(msg)}`;
-        self.console.error(msgWithPrefix);
-        self.console.error(msg);
-        pushLog(msgWithPrefix);
+    warn(obj: unknown) {
+        if (globalLevel < LogLevel.High || this.level < LogLevel.High) {
+            return;
+        }
+        console.warn(
+            `%cWARN%c${this.name}%c ${obj}`,
+            "background:orange;color:white;padding:0 3px",
+            this.color,
+            "color:inherit;background:inherit",
+        );
+    }
+
+    error(obj: unknown) {
+        if (globalLevel < LogLevel.High || this.level < LogLevel.High) {
+            return;
+        }
+        const msg = errstr(obj);
+        console.error(
+            `%cERROR%c${this.name}%c ${msg}`,
+            "background:orange;color:white;padding:0 3px",
+            this.color,
+            "color:inherit;background:inherit",
+        );
+        if (msg !== obj) {
+            console.error(obj);
+        }
     }
 }

package/src/memory/async_erc.ts

@@ -0,0 +1,179 @@
+/**
+ * A holder for an externally ref-counted object, where free and addref
+ * operations are asynchronous.
+ *
+ * See {@link makeErcType} for how to use
+ */
+export type AsyncErc<TName, TRepr = number> = {
+    readonly type: TName;
+
+    /**
+     * Underlying object representation.
+     *
+     * The repr should not be undefinable. undefined means nullptr
+     */
+    readonly value: TRepr | undefined;
+
+    /**
+     * Free the underlying object.
+     *
+     * All weak references will be immediately invalidated, and this Erc becomes
+     * empty. Awaiting on the promise will ensure that the object is freed externally
+     */
+    free: () => Promise<void>;
+
+    /**
+     * Assign a new value to this Erc.
+     *
+     * The old value will be freed, and all weak references will be invalidated.
+     */
+    assign: (value: TRepr | undefined) => Promise<void>;
+
+    /**
+     * Take the inner value without freeing it.
+     *
+     * All weak references will be invalidated, and this Erc will become
+     * empty
+     */
+    take: () => TRepr | undefined;
+
+    /**
+     * Create a weak reference to the inner value.
+     *
+     * When this Erc is freed, all weak references will be invalidated.
+     */
+    getWeak: () => AsyncErcRef<TName, TRepr>;
+
+    /**
+     * Create a strong reference to the inner value, essentially
+     * incrementing the ref count.
+     */
+    getStrong: () => Promise<AsyncErc<TName, TRepr>>;
+};
+
+/**
+ * Weak reference to an externally ref-counted object.
+ *
+ * See {@link makeErcType} for how to use
+ */
+export type AsyncErcRef<TName, TRepr = number> = {
+    readonly type: TName;
+
+    /**
+     * The underlying object representation.
+     *
+     * This may become undefined across async calls if the weak reference
+     * is invalidated
+     */
+    readonly value: TRepr | undefined;
+
+    /**
+     * Create a strong reference to the inner value, essentially
+     * incrementing the ref count.
+     */
+    getStrong: () => Promise<AsyncErc<TName, TRepr>>;
+};
+
+export type AsyncErcRefType<T> =
+    T extends AsyncErc<infer TName, infer TRepr>
+        ? AsyncErcRef<TName, TRepr>
+        : never;
+
+export type AsyncErcTypeConstructor<TName, TRepr> = {
+    /**
+     * A marker value for the underlying object type.
+     *
+     * This is commonly a string literal or a symbol.
+     */
+    marker: TName;
+
+    /**
+     * The function to free the underlying object.
+     */
+    free: (value: TRepr) => Promise<void> | void;
+
+    /**
+     * Given a value, increase the ref count and return the new reference.
+     * The returned representation should be a different value if double indirection
+     * is used (each value is a pointer to the smart pointer), or the same value
+     * if single indirection is used (the value is pointing to the object itself).
+     */
+    addRef: (value: TRepr) => Promise<TRepr> | TRepr;
+};
+
+/** See {@link makeErcType} */
+export const makeAsyncErcType = <TName, TRepr>({
+    marker,
+    free,
+    addRef,
+}: AsyncErcTypeConstructor<TName, TRepr>): ((
+    value: TRepr | undefined,
+) => AsyncErc<TName, TRepr>) => {
+    const createStrongRef = (
+        value: TRepr | undefined,
+    ): AsyncErc<TName, TRepr> => {
+        let weakRef:
+            | (AsyncErcRef<TName, TRepr> & { invalidate: () => void })
+            | undefined = undefined;
+        const invalidateWeakRef = () => {
+            if (!weakRef) {
+                return;
+            }
+            const oldWeakRef = weakRef;
+            weakRef = undefined;
+            oldWeakRef.invalidate();
+        };
+        const createWeakRef = (initialValue: TRepr | undefined) => {
+            const weak = {
+                type: marker,
+                value: initialValue,
+                invalidate: () => {
+                    weak.value = undefined;
+                },
+                getStrong: async () => {
+                    if (weak.value === undefined) {
+                        return createStrongRef(undefined);
+                    }
+                    return createStrongRef(await addRef(weak.value));
+                },
+            };
+            return weak;
+        };
+        const erc = {
+            type: marker,
+            value,
+            free: async () => {
+                if (erc.value !== undefined) {
+                    invalidateWeakRef();
+                    const freePromise = free(erc.value);
+                    erc.value = undefined;
+                    await freePromise;
+                }
+            },
+            assign: async (newValue: TRepr | undefined) => {
+                await erc.free();
+                erc.value = newValue;
+            },
+            take: () => {
+                invalidateWeakRef();
+                const oldValue = erc.value;
+                erc.value = undefined;
+                return oldValue;
+            },
+            getWeak: () => {
+                if (!weakRef) {
+                    weakRef = createWeakRef(erc.value);
+                }
+                return weakRef;
+            },
+            getStrong: async () => {
+                if (erc.value === undefined) {
+                    return createStrongRef(undefined);
+                }
+                return createStrongRef(await addRef(erc.value));
+            },
+        };
+        return erc;
+    };
+    return createStrongRef;
+};

package/src/memory/idgen.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { idgen, safeidgen } from "./idgen.ts";
+
+describe("idgen", () => {
+    it("idgen generates ids", () => {
+        const idgen1 = idgen();
+        const idgen2 = idgen();
+        expect(idgen1()).toBe(2);
+        expect(idgen2()).toBe(2);
+        expect(idgen1()).toBe(3);
+        expect(idgen2()).toBe(3);
+        expect(idgen1()).toBe(4);
+        expect(idgen2()).toBe(4);
+    });
+    it("safeidgen wraps", () => {
+        const x = safeidgen(5);
+        expect(x()).toBe(2);
+        expect(x()).toBe(3);
+        expect(x()).toBe(4);
+        expect(x()).toBe(1);
+        expect(x()).toBe(2);
+        expect(x()).toBe(3);
+        expect(x()).toBe(4);
+    });
+});

package/src/memory/idgen.ts

@@ -0,0 +1,40 @@
+/**
+ * Return an id generator that will generate ids in order
+ * from 1 to n, wrapping around to 1 when it's n
+ */
+export const safeidgen = (n: number): (() => number) => {
+    let x = 1;
+    return () => {
+        x += 1;
+        if (x === n) {
+            x = 1;
+        }
+        return x;
+    };
+};
+
+/**
+ * Return an id generator that returns bigint,
+ * starting from 1n, and will always return a new bigint
+ */
+export const bidgen = (): (() => bigint) => {
+    let x = 1n;
+    return () => {
+        x += 1n;
+        return x;
+    };
+};
+
+/**
+ * Returns an id generator that returns number staring from 1
+ * and always increasing. The number could become inaccurate
+ * (not integer) when exceeding Number.MAX_SAFE_INTEGER (which
+ * is 2^53 - 1
+ */
+export const idgen = (): (() => number) => {
+    let x = 1;
+    return () => {
+        x += 1;
+        return x;
+    };
+};

package/src/memory/index.ts

@@ -7,3 +7,4 @@
 export { cell, type CellConstructor, type Cell } from "./cell.ts";
 export { persist, type PersistConstructor, type Persist } from "./persist.ts";
 export * from "./erc.ts";
+export * from "./async_erc.ts";

package/src/pref/dark.ts

@@ -1,5 +1,5 @@
 import { persist } from "../memory/persist.ts";
-import { injectStyle } from "./injectStyle.ts";
+import { injectStyle } from "./inject_style.ts";
 
 const dark = persist({
     initial: false,

package/src/pref/index.ts

@@ -8,5 +8,5 @@
  * @module
  */
 export * from "./dark.ts";
-export * from "./injectStyle.ts";
+export * from "./inject_style.ts";
 export * from "./locale.ts";

package/src/pref/locale.ts

@@ -189,7 +189,7 @@ export const setLocale = (newLocale: string): boolean => {
         return true;
     }
     settingLocale = supported;
-    onBeforeChangeHook(supported).then((result) => {
+    void onBeforeChangeHook(supported).then((result) => {
         if (result.err) {
             return;
         }

package/src/sync/batch.ts

@@ -214,7 +214,7 @@ class BatchImpl<TFn extends AnyFn> {
         let done = this.disregardExecutionTime;
         setTimeout(() => {
             if (done) {
-                this.scheduleNext();
+                void this.scheduleNext();
             } else {
                 done = true;
             }
@@ -225,7 +225,7 @@ class BatchImpl<TFn extends AnyFn> {
             if (!this.disregardExecutionTime) {
                 if (done) {
                     // interval already passed, we need to call it
-                    this.scheduleNext();
+                    void this.scheduleNext();
                 } else {
                     done = true;
                 }