@pistonite/pure 0.27.1 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pistonite/pure",
-  "version": "0.27.1",
+  "version": "0.29.0",
   "type": "module",
   "description": "Pure TypeScript libraries for my projects",
   "homepage": "https://github.com/Pistonite/pure",
@@ -10,25 +10,34 @@
   "license": "MIT",
   "author": "Pistonight <pistonknight@outlook.com>",
   "files": [
-    "src/**/*",
-    "!src/**/*.test.ts"
+    "dist/**/*",
+    "src/**/*"
   ],
   "exports": {
-    "./fs": "./src/fs/index.ts",
-    "./log": "./src/log/index.ts",
-    "./memory": "./src/memory/index.ts",
-    "./result": "./src/result/index.ts",
-    "./sync": "./src/sync/index.ts",
-    "./pref": "./src/pref/index.ts"
+    "./log": {
+      "import": "./dist/log/index.js",
+      "types": "./dist/_dts_/src/log/index.d.ts"
+    },
+    "./memory": {
+      "import": "./dist/memory/index.js",
+      "types": "./dist/_dts_/src/memory/index.d.ts"
+    },
+    "./result": {
+      "import": "./dist/result/index.js",
+      "types": "./dist/_dts_/src/result/index.d.ts"
+    },
+    "./sync": {
+      "import": "./dist/sync/index.js",
+      "types": "./dist/_dts_/src/sync/index.d.ts"
+    }
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Pistonite/pure.git",
-    "directory": "packages/pure"
+    "url": "git+https://github.com/Pistonite/pure.git"
   },
   "devDependencies": {
-    "vitest": "^3.2.4",
-    "mono-dev": "0.2.5"
+    "eslint": "^9",
+    "mono-dev": "link:./mono-dev"
   },
   "dependencies": {
     "denque": "^2.1.0"

package/src/env.d.ts

@@ -1 +1,2 @@
 /// <reference lib="dom" />
+/// <reference types="mono-dev/vitest-types" />

package/src/log/index.ts

@@ -1,11 +1,36 @@
-export {
-    globalLogOff,
-    globalLogInfo,
-    globalLogDebug,
-    logger,
-    type LoggerFactory,
-    type Logger,
-    resettableLogger,
-    type ResettableLogger,
-} from "./logger.ts";
-export { internalLogOff, internalLogDebug, internalLogInfo } from "./internal.ts";
+/**
+ * Client side log util
+ *
+ * This is rather simple logging stuff with the primary focus
+ * being easy-to-debug, instead of optimized for bundle size or performance.
+ *
+ * Because this library doesn't have global states, there is no "global" logger
+ * or any global logger settings. Instead, each library or component of the
+ * application can create their own instance of the logger, which stores
+ * settings like the name, color and level of that logger.
+ *
+ * ```typescript
+ * import { logger } from "@pistonite/pure";
+ *
+ * export const myLogger = logger("my-library", {
+ *     color: "#ff8800", // any CSS color (note that styling only works in browser)
+ * });
+ * ```
+ *
+ * It's recommended that a library exports the logger object
+ * so downstream app can modify the logging level if needed for debugging.
+ * ```typescript
+ * import { myLogger } from "my-library";
+ *
+ * myLogger.setLevel("debug");
+ * ```
+ *
+ * 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
+ */
+export { type LogLevelStr, type LoggerConstructor, type Logger, logger } from "./logger.ts";

package/src/log/logger.ts

@@ -1,106 +1,39 @@
-/**
- * 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 { errstr } from "../result/index.ts";
 
-export const LogLevel = { Off: 0, High: 1, Info: 2, Debug: 3 } as const;
-export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
-
-let globalLevel: LogLevel = LogLevel.High;
-/**
- * Suppress ALL logging.
- *
- * This overrides logger-level settings
- */
-export const globalLogOff = () => {
-    globalLevel = LogLevel.Off;
-};
 /**
- * Enable +info logging for ALL loggers
+ * String-enum for logging levels
  *
- * This overrides logger-level settings
+ * off - no logging at all
+ * default - warning and errors only
+ * info - warning, errors, info
+ * debug - warning, errors, info, debug
  */
-export const globalLogInfo = () => {
-    globalLevel = LogLevel.Info;
-};
-/**
- * Enable +debug logging for ALL loggers
- *
- * This overrides logger-level settings
- */
-export const globalLogDebug = () => {
-    globalLevel = LogLevel.Debug;
-};
-
-/** 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),
-    };
-};
-
-/** Create a {@link ResettableLogger} that can be easily reconfigured */
-export const resettableLogger = (name: string, color?: string): ResettableLogger => {
-    const logger = new LoggerImpl(name, color, LogLevel.High);
-    return {
-        logger,
-        debug: () => (logger.level = LogLevel.Debug),
-        info: () => (logger.level = LogLevel.Info),
-        off: () => (logger.level = LogLevel.Off),
-    };
-};
 
-/**
- * A logger whose level can be changed later. Useful for libraries to expose,
- * so users can easily debug calls in the library
- */
-export type ResettableLogger = {
-    logger: Logger;
-    debug(): void;
-    info(): void;
-    off(): void;
-};
+const LogLevel = { off: 0, default: 1, info: 2, debug: 3 } as const;
+export type LogLevelStr = "off" | "default" | "info" | "debug";
+if (import.meta.vitest) {
+    const { test, expectTypeOf } = import.meta.vitest;
+    test("type LogLevelStr", () => {
+        expectTypeOf<LogLevelStr>().toEqualTypeOf<keyof typeof LogLevel>();
+    });
+}
+type LogLevel = (typeof LogLevel)[LogLevelStr];
 
-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;
-};
+/** Args for constructing a logger */
+export interface LoggerConstructor {
+    /** CSS Color for the logger, default is 'gray' */
+    color?: string;
+    /**
+     * Logging level, default is "default".
+     * The level can still be changed later with setLevel
+     */
+    level?: LogLevelStr;
+}
 
-export type Logger = {
+/** The logger type */
+export interface Logger {
+    /** Set the level of the logger */
+    setLevel(level: LogLevelStr): void;
     /** Log a debug message */
     debug(obj: unknown): void;
     /** Log an info message */
@@ -109,21 +42,69 @@ export type Logger = {
     warn(obj: unknown): void;
     /** Log an error message */
     error(obj: unknown): void;
-};
+}
 
-export class LoggerImpl implements Logger {
-    name: string;
-    color: string | undefined;
-    level: LogLevel;
+/** Create a logger creator. Use the factory methods to finish making the logger */
+export const logger = (name: string, args: LoggerConstructor): Logger => {
+    const { color, level } = args;
+    const levelObj = LogLevel[level || "off"] || LogLevel.off;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if ((globalThis as any).process) {
+        return new BareLoggerImpl(name, levelObj);
+    }
+    const color2 = color || "gray";
+    return new CssLoggerImpl(name, color2, levelObj);
+};
 
-    constructor(name: string, color: string | undefined, level: LogLevel) {
-        this.name = name;
-        this.color = "padding:0 3x;color:white" + (color ? `;background:${color}` : "");
-        this.level = level;
+class BareLoggerImpl implements Logger {
+    constructor(
+        private name: string,
+        private level: LogLevel,
+    ) {}
+    setLevel(level: LogLevelStr): void {
+        this.level = LogLevel[level] || LogLevel["off"];
+    }
+    debug(obj: unknown): void {
+        if (this.level !== LogLevel.debug) {
+            return;
+        }
+        console.debug(`DEBUG [${this.name}] ${obj}`);
+    }
+    info(obj: unknown): void {
+        if (this.level < LogLevel.info) {
+            return;
+        }
+        console.info(`INFO [${this.name}] ${obj}`);
+    }
+    warn(obj: unknown): void {
+        if (this.level < LogLevel.default) {
+            return;
+        }
+        console.warn(`WARN [${this.name}] ${obj}`);
+    }
+    error(obj: unknown): void {
+        if (this.level < LogLevel.default) {
+            return;
+        }
+        const msg = errstr(obj);
+        console.error(`ERROR [${this.name}] ${msg}`);
+        if (msg !== obj) {
+            console.error(obj);
+        }
     }
+}
 
-    debug(obj: unknown) {
-        if (globalLevel !== LogLevel.Debug && this.level !== LogLevel.Debug) {
+class CssLoggerImpl implements Logger {
+    constructor(
+        private name: string,
+        private color: string,
+        private level: LogLevel,
+    ) {}
+    setLevel(level: LogLevelStr): void {
+        this.level = LogLevel[level] || LogLevel["off"];
+    }
+    debug(obj: unknown): void {
+        if (this.level !== LogLevel.debug) {
             return;
         }
         console.debug(
@@ -133,9 +114,8 @@ export class LoggerImpl implements Logger {
             "color:inherit;background:inherit",
         );
     }
-
-    info(obj: unknown) {
-        if (globalLevel < LogLevel.Info && this.level < LogLevel.Info) {
+    info(obj: unknown): void {
+        if (this.level < LogLevel.info) {
             return;
         }
         console.info(
@@ -145,9 +125,8 @@ export class LoggerImpl implements Logger {
             "color:inherit;background:inherit",
         );
     }
-
-    warn(obj: unknown) {
-        if (globalLevel < LogLevel.High || this.level < LogLevel.High) {
+    warn(obj: unknown): void {
+        if (this.level < LogLevel.default) {
             return;
         }
         console.warn(
@@ -157,9 +136,8 @@ export class LoggerImpl implements Logger {
             "color:inherit;background:inherit",
         );
     }
-
-    error(obj: unknown) {
-        if (globalLevel < LogLevel.High || this.level < LogLevel.High) {
+    error(obj: unknown): void {
+        if (this.level < LogLevel.default) {
             return;
         }
         const msg = errstr(obj);

package/src/memory/cell.ts

@@ -1,21 +1,31 @@
-/**
- * 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);
-}
+/** Create a {@link Cell} */
+export const cell = <T>(args: CellConstructor<T>): Cell<T> => {
+    return new CellImpl(args.initial);
+};
 
-export type CellConstructor<T> = {
+/** Args for constructing a cell */
+export interface CellConstructor<T> {
     /** Initial value */
     initial: T;
-};
+}
 
-export type Cell<T> = {
+/**
+ * A light weight storage wrapper around a value
+ * that can be subscribed to for changes
+ *
+ * Created via `cell()`
+ *
+ * ```typescript
+ * import { cell } from "@pistonite/pure/memory";
+ *
+ * const myCell = cell(true);
+ * ```
+ */
+export interface 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)[] = [];

package/src/memory/emp.ts

@@ -39,31 +39,41 @@
  * In 32-bit context like WASM32, the inner value can be a `number`.
  * In 64-bit context, `number` might be fine for some systems, but `bigint`
  * is recommended.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // First create a marker to distinguish between different Emp types for TypeScript.
+ * // This is not used at runtime
+ * const MyNativeType = Symbol("MyNativeType");
+ * export type MyNativeType = typeof MyNativeType;
+ *
+ * // Then use makeEmpType to create a factory function
+ * const makeMyNativeTypeEmp = makeEmpType({
+ *     marker: MyNativeType,
+ *     free: (ptr) => freeMyNativeType(ptr),
+ * });
+ *
+ * // Now acquire ownership of an object from external native code
+ * // and assign it to an Emp
+ * const myObjRawPtr = allocMyNativeType();
+ * const myObj = makeMyNativeTypeEmp(myObjRawPtr);
+ *
+ * // when myObj is GC'ed, it will be freed by calling freeMyNativeType
+ * ```
  */
-export type Emp<T, TRepr> = {
+export interface Emp<T, TRepr> {
     /** The type marker for T. This only marks the type for TypeScript and does not exist at runtime */
     readonly __phantom: T;
     /** The underlying pointer value */
     readonly value: TRepr;
-};
+}
 
-export type EmpConstructor<T, TRepr> = {
+/** Args for constructing a Emp type */
+export interface EmpConstructor<T, TRepr> {
     /**
-     * The marker for the Emp type, used to distinguish between multiple types
-     *
-     * Typically, this is a unique symbol:
-     * ```typescript
-     * const MyNativeType = Symbol("MyNativeType");
-     * export type MyNativeType = typeof MyNativeType;
-     *
-     * const makeMyNativeTypeEmp = makeEmpType({
-     *     marker: MyNativeType,
-     *     free: (ptr) => void freeMyNativeType(ptr)
-     * })
-     * ```
-     *
-     * Note that this is not used in runtime, but just used for type inference,
-     * so you can also skip passing it and specify the type parameter instead
+     * The marker for the Emp type, used to distinguish between multiple Emp types
+     * in TypeScript
      */
     marker?: T;
 
@@ -71,14 +81,15 @@ export type EmpConstructor<T, TRepr> = {
      * Function to free the underlying object. Called when this Emp is garbage-collected
      */
     free: (ptr: TRepr) => void | Promise<void>;
-};
+}
 
 /**
- * Create a factory function for an {@link Emp} type.
+ * Create a factory function for an Emp type. See {@link Emp}
  */
-export const makeEmpType = <T, TRepr>({
-    free,
-}: EmpConstructor<T, TRepr>): ((ptr: TRepr) => Emp<T, TRepr>) => {
+export const makeEmpType = <T, TRepr>(
+    args: EmpConstructor<T, TRepr>,
+): ((ptr: TRepr) => Emp<T, TRepr>) => {
+    const { free } = args;
     const registry = new FinalizationRegistry(free);
     return (ptr: TRepr) => {
         const obj = Object.freeze({ value: ptr });

package/src/memory/idgen.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "mono-dev/vitest";
 
 import { idgen, safeidgen } from "./idgen.ts";
 

package/src/memory/index.ts

@@ -1,12 +1,9 @@
 /**
- * # pure/memory
- * JS memory utilities
+ * Memory utilities
  *
  * @module
  */
 export { cell, type CellConstructor, type Cell } from "./cell.ts";
 export { persist, type PersistConstructor, type Persist } from "./persist.ts";
-export * from "./async_erc.ts";
 export * from "./emp.ts";
-export * from "./erc.ts";
 export * from "./idgen.ts";

package/src/memory/persist.ts

@@ -3,13 +3,8 @@ import { cell, type Cell, type CellConstructor } from "./cell.ts";
 /**
  * Create a cell that persists its value to a web storage
  */
-export function persist<T>({
-    storage,
-    key,
-    serialize = JSON.stringify,
-    deserialize,
-    initial,
-}: PersistConstructor<T>): Persist<T> {
+export function persist<T>(args: PersistConstructor<T>): Persist<T> {
+    const { storage, key, serialize = JSON.stringify, deserialize, initial } = args;
     const deser =
         deserialize ??
         ((value: string) => {
@@ -22,7 +17,8 @@ export function persist<T>({
     return new PersistImpl(storage, key, serialize, deser, initial);
 }
 
-export type PersistConstructor<T> = CellConstructor<T> & {
+/** Args for creating a persisted cell */
+export interface PersistConstructor<T> extends CellConstructor<T> {
     /** The web storage to use */
     storage: Storage;
 
@@ -41,9 +37,10 @@ export type PersistConstructor<T> = CellConstructor<T> & {
      * By default, it will use `JSON.parse` wrapped with try-catch
      */
     deserialize?(value: string): T | null;
-};
+}
 
-export type Persist<T> = Cell<T> & {
+/** A cell that also persists its value */
+export interface Persist<T> extends Cell<T> {
     /**
      * Load the value initially, and notify all the current subscribers
      *
@@ -52,9 +49,9 @@ export type Persist<T> = Cell<T> & {
     init(initial?: T): T;
     /** Clear the value from the storage */
     clear(): void;
-    /** Clera the value and disable the persistence */
+    /** Clear the value and disable the persistence */
     disable(): void;
-};
+}
 
 class PersistImpl<T> implements Persist<T> {
     private cell: Cell<T>;

package/src/result/index.ts

@@ -1,4 +1,6 @@
 /**
+ * Rust-like `Result<T, E>` type and error handling utils
+ *
  * **I once had a fancy error object with TypeScript magic that tries
  * to reduce allocation while maintaining Result-safety. It turns out
  * that was slower than allocating plain objects for every return, because
@@ -163,9 +165,15 @@ export type Result<T, E> = Ok<T> | Err<E>;
 // This is to get type narrowing to work most of the time
 
 /** A success value */
-export type Ok<T> = { val: T; err?: never };
+export interface Ok<T> {
+    val: T;
+    err?: never;
+}
 /** An error value */
-export type Err<E> = { err: E; val?: never };
+export interface Err<E> {
+    err: E;
+    val?: never;
+}
 
 /**
  * A value that is either `void` or an error
@@ -177,7 +185,7 @@ export type Void<E> = { val?: never; err?: never } | { err: E };
 export type VoidOk = Record<string, never>;
 
 /** Wrap a function with try-catch and return a Result. */
-export function tryCatch<T, E = unknown>(fn: () => T): Result<T, E> {
+export function tryCatch<T, E = Error>(fn: () => T): Result<T, E> {
     try {
         return { val: fn() };
     } catch (e) {
@@ -186,7 +194,7 @@ export function tryCatch<T, E = unknown>(fn: () => T): Result<T, E> {
 }
 
 /** Wrap an async function with try-catch and return a Promise<Result>. */
-export async function tryAsync<T, E = unknown>(fn: () => Promise<T>): Promise<Result<T, E>> {
+export async function tryAsync<T, E = Error>(fn: () => Promise<T>): Promise<Result<T, E>> {
     try {
         return { val: await fn() };
     } catch (e) {

package/src/sync/batch.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "mono-dev/vitest";
 
 import { batch } from "./batch.ts";
 

package/src/sync/batch.ts

@@ -1,7 +1,16 @@
 import { type AnyFn, makePromise, type PromiseHandle, type AwaitRet } from "./util.ts";
 
+/** Factory for batched function. See {@link BatchConstructor} for usage. */
+export function batch<TFn extends AnyFn>(args: BatchConstructor<TFn>) {
+    const { fn, batch, unbatch, interval, disregardExecutionTime } = args;
+    const impl = new BatchImpl(fn, batch, unbatch, interval, !!disregardExecutionTime);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
 /**
- * An async event wrapper that allows multiple calls in an interval
+ * Options to construct a `batch` function
+ *
+ * A batch function is 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.
@@ -87,21 +96,7 @@ import { type AnyFn, makePromise, type PromiseHandle, type AwaitRet } from "./ut
  * ```
  *
  */
-export function batch<TFn extends AnyFn>({
-    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 AnyFn> = {
+export interface BatchConstructor<TFn extends AnyFn> {
     /** Function to be wrapped */
     fn: TFn;
     /** Function to batch the inputs across multiple calls */
@@ -122,7 +117,7 @@ export type BatchConstructor<TFn extends AnyFn> = {
 
     /** See `debounce` for more information */
     disregardExecutionTime?: boolean;
-};
+}
 
 class BatchImpl<TFn extends AnyFn> {
     private idle: boolean;

package/src/sync/capture.ts

@@ -1,3 +1,5 @@
+// this is an exception to the global state rule - since it doesn't really matter
+// if this is duplicated
 const captured = new Set<unknown>();
 
 /**

package/src/sync/debounce.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "mono-dev/vitest";
 
 import { debounce } from "./debounce.ts";