@pistonite/pure 0.28.0 → 0.29.1

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";
 

package/src/sync/debounce.ts

@@ -1,7 +1,16 @@
 import { type AnyFn, type AwaitRet, makePromise, type PromiseHandle } from "./util.ts";
 
+/** Factory for debounced function. See {@link DebounceConstructor} for usage */
+export function debounce<TFn extends AnyFn>(args: DebounceConstructor<TFn>) {
+    const { fn, interval, disregardExecutionTime } = args;
+    const impl = new DebounceImpl(fn, interval, !!disregardExecutionTime);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
 /**
- * An async event wrapper that is guaranteed to:
+ * Options for `debounce` function
+ *
+ * A debounced function is an async event wrapper that is guaranteed to:
  * - Not re-fire in a minimal interval after it's initialially fired.
  * - All calls will eventually fire
  *
@@ -78,19 +87,7 @@ import { type AnyFn, type AwaitRet, makePromise, type PromiseHandle } from "./ut
  * });
  * ```
  */
-export function debounce<TFn extends AnyFn>({
-    fn,
-    interval,
-    disregardExecutionTime,
-}: DebounceConstructor<TFn>) {
-    const impl = new DebounceImpl(fn, interval, !!disregardExecutionTime);
-    return (...args: Parameters<TFn>) => impl.invoke(...args);
-}
-
-/**
- * Options for `debounce` function
- */
-export type DebounceConstructor<TFn> = {
+export interface DebounceConstructor<TFn> {
     /** Function to be debounced */
     fn: TFn;
     /**
@@ -111,7 +108,7 @@ export type DebounceConstructor<TFn> = {
      * set this to true.
      */
     disregardExecutionTime?: boolean;
-};
+}
 
 class DebounceImpl<TFn extends AnyFn> {
     private idle: boolean;

package/src/sync/index.ts

@@ -1,6 +1,5 @@
 /**
- * # pure/sync
- * JS synchronization utilities
+ * Synchronization utilities
  *
  * @module
  */
@@ -10,7 +9,7 @@ export {
     type SerialEventCancelCallback,
     type SerialCancelToken,
 } from "./serial.ts";
-export { latest, type LatestConstructor, type UpdateArgsFn } from "./latest.ts";
+export { latest, type LatestConstructor, type LatestUpdateArgsFn } from "./latest.ts";
 export { debounce, type DebounceConstructor } from "./debounce.ts";
 export { batch, type BatchConstructor } from "./batch.ts";
 export { once, type OnceConstructor } from "./once.ts";

package/src/sync/latest.test.ts

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