@pistonite/pure 0.26.7 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pistonite/pure",
-  "version": "0.26.7",
+  "version": "0.27.0",
   "type": "module",
   "description": "Pure TypeScript libraries for my projects",
   "homepage": "https://github.com/Pistonite/pure",

package/src/memory/async_erc.ts

@@ -3,6 +3,8 @@
  * operations are asynchronous.
  *
  * See {@link makeErcType} for how to use
+ *
+ * @deprecated use Emp
  */
 export type AsyncErc<TName, TRepr = number> = {
     readonly type: TName;
@@ -55,6 +57,8 @@ export type AsyncErc<TName, TRepr = number> = {
  * Weak reference to an externally ref-counted object.
  *
  * See {@link makeErcType} for how to use
+ *
+ * @deprecated use Emp
  */
 export type AsyncErcRef<TName, TRepr = number> = {
     readonly type: TName;
@@ -74,11 +78,17 @@ export type AsyncErcRef<TName, TRepr = number> = {
     getStrong: () => Promise<AsyncErc<TName, TRepr>>;
 };
 
+/**
+ * @deprecated use Emp
+ */
 export type AsyncErcRefType<T> =
     T extends AsyncErc<infer TName, infer TRepr>
         ? AsyncErcRef<TName, TRepr>
         : never;
 
+/**
+ * @deprecated use Emp
+ */
 export type AsyncErcTypeConstructor<TName, TRepr> = {
     /**
      * A marker value for the underlying object type.
@@ -101,7 +111,9 @@ export type AsyncErcTypeConstructor<TName, TRepr> = {
     addRef: (value: TRepr) => Promise<TRepr> | TRepr;
 };
 
-/** See {@link makeErcType} */
+/**
+ * @deprecated use Emp
+ */
 export const makeAsyncErcType = <TName, TRepr>({
     marker,
     free,

package/src/memory/emp.ts

@@ -0,0 +1,88 @@
+/**
+ * A non-null, **E**ngine-**m**anaged **P**ointer
+ *
+ * This uses the ECMA FinalizationRegistry, to free the resource,
+ * once this object is garbage-collected.
+ *
+ * The free function may be async.
+ *
+ * ## Use case
+ * When JS interoperates with a system language like C/C++ or Rust,
+ * it is often needed to transfer objects into JS context. If the object
+ * is big, copy-transfer could be expensive, so the more ideal solution
+ * is to transfer a "handle", or a pointer, to JS, and leaving the actual
+ * object in the native memory. Then, JS code and pass the pointer to external
+ * code to use or extract data from the object when needed.
+ *
+ * This approach is just like passing raw pointers in C, which means it is
+ * extremely succeptible to memory corruption bugs like double-free or
+ * use-after-free. Unlike C++ or Rust, JS also doesn't have destructors
+ * that run when an object leaves the scope (proposal for the `using` keyword exists,
+ * but you can actually double-free the object with `using`).
+ *
+ * C-style manual memory management might be sufficient for simple bindings,
+ * but for more complex scenarios, automatic memory management is needed,
+ * by tying the free call to the GC of a JS object.
+ *
+ * ## Recommended practice
+ * 1. The external code should transfer the ownership of the object
+ *    to JS when passing it to JS. JS will then put the handle into an Emp
+ *    to be automatically managed. This means the external code should now
+ *    never free the object, and let JS free it instead.
+ * 2. The inner value of the Emp must only be used for calling
+ *    external code, and the Emp must be kept alive for all runtimes, including
+ *    those with heavy optimization that may reclaim the Emp during the call,
+ *    if it's not referenced afterwards. See {@link scopedCapture}.
+ *    The inner value must not dangle around outside of the Emp that owns it.
+ *
+ * ## Pointer Size
+ * 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.
+ */
+export type 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> = {
+    /**
+     * 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
+     */
+    marker?: T;
+
+    /**
+     * 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.
+ */
+export const makeEmpType = <T, TRepr>({
+    free,
+}: EmpConstructor<T, TRepr>): ((ptr: TRepr) => Emp<T, TRepr>) => {
+    const registry = new FinalizationRegistry(free);
+    return (ptr: TRepr) => {
+        const obj = Object.freeze({ value: ptr });
+        registry.register(obj, ptr);
+        return obj as Emp<T, TRepr>;
+    };
+};

package/src/memory/erc.ts

@@ -2,6 +2,7 @@
  * A holder for an externally ref-counted object.
  *
  * See {@link makeErcType} for how to use
+ * @deprecated use Emp
  */
 export type Erc<TName, TRepr = number> = {
     readonly type: TName;
@@ -54,6 +55,7 @@ export type Erc<TName, TRepr = number> = {
  * Weak reference to an externally ref-counted object.
  *
  * See {@link makeErcType} for how to use
+ * @deprecated use Emp
  */
 export type ErcRef<TName, TRepr = number> = {
     readonly type: TName;
@@ -73,9 +75,15 @@ export type ErcRef<TName, TRepr = number> = {
     getStrong: () => Erc<TName, TRepr>;
 };
 
+/**
+ * @deprecated use Emp
+ */
 export type ErcRefType<T> =
     T extends Erc<infer TName, infer TRepr> ? ErcRef<TName, TRepr> : never;
 
+/**
+ * @deprecated use Emp
+ */
 export type ErcTypeConstructor<TName, TRepr> = {
     /**
      * A marker value for the underlying object type.
@@ -241,6 +249,7 @@ export type ErcTypeConstructor<TName, TRepr> = {
  * myFoo1.assign(myFoo1.value); // this will free the value since ref count is 0, and result in a dangling pointer
  * ```
  *
+ * @deprecated use Emp
  */
 export const makeErcType = <TName, TRepr>({
     marker,

package/src/memory/index.ts

@@ -6,6 +6,7 @@
  */
 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";
+export * from "./emp.ts";
+export * from "./erc.ts";
 export * from "./idgen.ts";

package/src/pref/device.ts

@@ -0,0 +1,127 @@
+import { ilog } from "../log/internal.ts";
+import { cell } from "../memory";
+
+let cachedIsMobile: boolean | undefined = undefined;
+
+/** Check if the current UserAgent is a mobile device */
+export const isMobile = (): boolean => {
+    // just very primitive UA parsing for now,
+    // we don't need to take another dependency just to detect
+    // a few platforms
+    if (cachedIsMobile === undefined) {
+        const ua = navigator?.userAgent || "";
+        if (ua.match(/(Windows NT|Macintosh|)/i)) {
+            cachedIsMobile = false;
+        } else if (ua.match(/(Mobil|iPhone|Android|iPod|iPad)/)) {
+            cachedIsMobile = true;
+        } else if (ua.includes("Linux")) {
+            cachedIsMobile = false;
+        } else {
+            ilog.warn("unable to determine device type, assuming desktop");
+            cachedIsMobile = true;
+        }
+    }
+    return cachedIsMobile;
+};
+
+// stores current display mode
+const displayMode = cell({ initial: "" });
+
+/**
+ * Options for display mode detection
+ *
+ * See {@link initDisplayMode}
+ */
+export type DisplayModeOptions<T extends string> = {
+    /**
+     * Set the initial value, if the platform doesn't support detecting
+     * the display mode. `detect()` will be used instead if supported
+     */
+    initial?: T;
+    /**
+     * Function to determine the display mode based on viewport width and height,
+     * and if the device is mobile
+     */
+    detect: (width: number, height: number, isMobile: boolean) => T;
+};
+
+/**
+ * Initialize display mode detection for the app.
+ *
+ * The display mode may be based on the viewport dimensions
+ * and if the device is mobile. Also note that you can use {@link isMobile}
+ * without the display mode framework.
+ *
+ * The display modes are strings that should be passed as a type parameter
+ * to {@link initDisplayMode}. You can create an alias in your code for
+ * getting the typed version of {@link addDisplayModeSubscriber}, {@link getDisplayMode},
+ * and {@link useDisplayMode} from `pure-react`.
+ *
+ * ```typescript
+ * import {
+ *     addDisplayModeSubscriber as pureAddDisplayModeSubscriber,
+ *     getDisplayMode as pureGetDisplayMode,
+ * } from "@pistonite/pure/pref";
+ * import { useDisplayMode as pureUseDisplayMode } from "@pistonite/pure-react";
+ *
+ * export const MyDisplayModes = ["mode1", "mode2"] as const;
+ * export type MyDisplayMode = (typeof MyDisplayModes)[number];
+ *
+ * export const addDisplayModeSubscriber = pureAddDisplayModeSubscriber<MyDisplayMode>;
+ * export const getDisplayMode = pureGetDisplayMode<MyDisplayMode>;
+ * export const useDisplayMode = pureUseDisplayMode<MyDisplayMode>;
+ * ```
+ *
+ * Note that this is not necessary in some simple use cases. For example,
+ * adjusting styles based on the viewport width can be done with CSS:
+ * ```css
+ * @media screen and (max-width: 800px) {
+ *    /* styles for narrow mode * /
+ * }
+ * ```
+ *
+ * Use this only if the display mode needs to be detected programmatically.
+ */
+export const initDisplayMode = <T extends string>(
+    options: DisplayModeOptions<T>,
+) => {
+    const detectCallback = () => {
+        const mode = options.detect(
+            window.innerWidth,
+            window.innerHeight,
+            isMobile(),
+        );
+        displayMode.set(mode);
+    };
+    if (
+        window &&
+        window.addEventListener &&
+        window.innerWidth !== undefined &&
+        window.innerHeight !== undefined
+    ) {
+        window.addEventListener("resize", detectCallback);
+        detectCallback();
+    } else if (options.initial !== undefined) {
+        displayMode.set(options.initial);
+    } else {
+        ilog.warn(
+            "display mode cannot be initialized, since detection is not supported and initial is not set",
+        );
+    }
+};
+
+/** Subscribe to display mode changes */
+export const addDisplayModeSubscriber = <T extends string>(
+    subscriber: (mode: T) => void,
+    notifyImmediately?: boolean,
+) => {
+    return displayMode.subscribe(
+        subscriber as (x: string) => void,
+        notifyImmediately,
+    );
+};
+
+/** Get the current display mode */
+export const getDisplayMode = <T extends string>(): T => {
+    return displayMode.get() as T;
+};

package/src/pref/index.ts

@@ -10,3 +10,4 @@
 export * from "./dark.ts";
 export * from "./inject_style.ts";
 export * from "./locale.ts";
+export * from "./device.ts";

package/src/sync/RwLock.ts

@@ -6,6 +6,8 @@ import Deque from "denque";
  * Only guaranteed if no one else has reference to the inner object
  *
  * It can take a second type parameter to specify interface with write methods
+ *
+ * @deprecated unstable API
  */
 export class RwLock<TRead, TWrite extends TRead = TRead> {
     /**

package/src/sync/capture.ts

@@ -0,0 +1,36 @@
+const captured = new Set<unknown>();
+
+/**
+ * Execute an async closure `fn`, and guarantee that `obj` will not be
+ * garbage-collected, until the promise is resolved.
+ */
+export const scopedCapture = async <T>(
+    fn: () => Promise<T>,
+    obj: unknown,
+): Promise<T> => {
+    // captures the object
+    // technically, this is not needed, as the delete() call above
+    // should make sure the captured object is not GC'ed.
+    // However, making it reachable from a global object will definitely
+    // prevent GC even with crazy optimization from any runtime
+    captured.add(obj);
+    try {
+        return await fn();
+    } finally {
+        captured.delete(obj);
+    }
+};
+
+/**
+ * Execute a closure `fn`, and guarantee that `obj` will not be
+ * garbage-collected during the execution
+ */
+export const scopedCaptureSync = <T>(fn: () => T, obj: unknown): T => {
+    // captures the object
+    captured.add(obj);
+    try {
+        return fn();
+    } finally {
+        captured.delete(obj);
+    }
+};

package/src/sync/index.ts

@@ -14,8 +14,10 @@ export { latest, type LatestConstructor, type UpdateArgsFn } from "./latest.ts";
 export { debounce, type DebounceConstructor } from "./debounce.ts";
 export { batch, type BatchConstructor } from "./batch.ts";
 export { once, type OnceConstructor } from "./once.ts";
+export { makePromise, type PromiseHandle } from "./util.ts";
+export { scopedCapture, scopedCaptureSync } from "./capture.ts";
 
-// types
+// helper types
 export type { AnyFn, AwaitRet } from "./util.ts";
 
 // unstable

package/src/sync/mutex.ts

@@ -0,0 +1,21 @@
+/**
+ * Non-reentrant mutex
+ *
+ * This allows only one context to enter a block at a time in a FIFO manner.
+ *
+ * This mutex is non-reentrant. Trying to lock it again while the same
+ * context already owns the lock will cause a dead lock.
+ *
+ * While a context id can be used to implement reentrant locks,
+ * it is very cumbersome to use. https://github.com/tc39/proposal-async-context
+ * will allow for a cleaner implementation.
+ */
+// TODO: implement it if needed
+// export class Mutex {
+//     private waiters: Deque;
+//
+//     constructor() {
+//         this.waiters = new
+//     }
+//
+// }

package/src/sync/util.ts

@@ -1,23 +1,28 @@
-export const makePromise = <T>(): {
-    promise: Promise<T>;
-    resolve: (value: T | PromiseLike<T>) => void;
-    reject: (reason?: unknown) => void;
-} => {
-    let resolve;
-    let reject;
+/**
+ * Make a {@link PromiseHandle} with the promise object separate from
+ * its resolve and reject methods
+ */
+export const makePromise = <T>(): PromiseHandle<T> => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let resolve: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let reject: any;
     const promise = new Promise<T>((res, rej) => {
         resolve = res;
         reject = rej;
     });
-    if (!resolve || !reject) {
-        throw new Error(
-            "Promise callbacks not set. This is a bug in the JS engine!",
-        );
-    }
     return { promise, resolve, reject };
 };
 
-export type PromiseHandle<T> = ReturnType<typeof makePromise<T>>;
+/**
+ * A handle of the promise that breaks down the promise object
+ * and its resolve and reject functions
+ */
+export type PromiseHandle<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+};
 
 /** Shorthand for Awaited<ReturnType<T>> */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any