@pistonite/pure 0.28.0 → 0.29.1

package/src/memory/erc.ts

@@ -1,320 +0,0 @@
-/**
- * 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;
-
-    /**
-     * 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 invalidated, and this Erc will become
-     * empty
-     */
-    free: () => 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) => 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: () => ErcRef<TName, TRepr>;
-
-    /**
-     * Create a strong reference to the inner value, essentially
-     * incrementing the ref count.
-     */
-    getStrong: () => Erc<TName, TRepr>;
-};
-
-/**
- * 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;
-
-    /**
-     * 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: () => 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.
-     *
-     * This is commonly a string literal or a symbol.
-     */
-    marker: TName;
-
-    /**
-     * The function to free the underlying object.
-     */
-    free: (value: TRepr) => 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) => TRepr;
-};
-
-/**
- * Create a constructor function that serves as the type for an externally ref-counted
- * object type. Erc instances can then be created for manually managing memory for
- * external objects, typically through FFI.
- *
- * Since JS is garbage collected and has no way to enforce certain memory management,
- * the programmer must ensure that Erc instances are handled correctly!!!
- *
- * ## Defining Erc type
- * ```typescript
- * import { makeErcType, type Erc } from "@pistonite/pure/memory";
- *
- * // 2 functions are required to create an Erc type:
- * // free: free the underlying value (essentially decrementing the ref count)
- * // addRef: increment the ref count and return the new reference
- *
- * // here, assume `number` is the JS type used to represent the external object
- * // for example, this can be a pointer to a C++ object
- * declare function freeFoo(obj: number) => void;
- * declare function addRefFoo(obj: number) => number;
- *
- * // assume another function to create (allocate) the object
- * declare function createFoo(): number;
- *
- * // The recommended way is to create a unique symbol for tracking
- * // the external type, you can also use a string literal
- * const Foo = Symbol("Foo");
- * type Foo = typeof Foo;
- *
- * // now, we can create the Erc type
- * const makeFooErc = makeErcType({
- *     marker: Foo,
- *     free: freeFoo,
- *     addRef: addRefFoo,
- * });
- *
- * // and create Erc instances
- * const myFoo: Erc<Foo> = makeFooErc(createFoo());
- * ```
- *
- * ## Using Erc (strong reference)
- * Each `Erc` instance is a strong reference, corresponding to some ref-counted
- * object externally. Therefore, owner of the `Erc` instance should
- * not expose the `Erc` instance to others (for example, returning it from a function),
- * since it will lead to memory leak or double free.
- * ```typescript
- * // create a foo instance externally, and wrap it with Erc
- * const myFoo = makeFooErc(createFoo());
- *
- * // if ownership of myFoo should be returned to external, use `take()`
- * // this will make myFoo empty, and doSomethingWithFooExternally should free it
- * doSomethingWithFooExternally(myFoo.take());
- *
- * // you can also free it directly
- * foo.free();
- * ```
- *
- * ## Using ErcRef (weak reference)
- * Calling `getWeak` on an `Erc` will return a weak reference that has the same
- * inner value. The weak reference is safe to be passed around and copied.
- * ```typescript
- * const myFooWeak = myFoo.getWeak();
- * ```
- *
- * The weak references are tracked by the `Erc` instance.
- * In the example above, when `myFoo` is freed, all weak references created by
- * `getWeak` will be invalidated. If some other code kept the inner value of
- * the weak reference, it will become a dangling pointer.
- *
- * To avoid this, `getStrong` can be used to create a strong reference if
- * the weak reference is still valid, to ensure that the underlying object
- * is never freed while still in use
- * ```typescript
- * const myFooWeak = myFoo.getWeak();
- *
- * // assume we have some async code that needs to use myFoo
- * declare async function doSomethingWithFoo(foo: FooErcRef): Promise<void>;
- *
- * // Below is BAD!
- * await doSomethingWithFoo(myFooWeak);
- * // Reason: doSomethingWithFoo is async, so it's possible that
- * // myFooWeak is invalidated when it's still needed. If the implementation
- * // does not check for that, it could be deferencing a dangling pointer
- * // (of course, it could actually be fine depending on the implementation of doSomethingWithFoo)
- *
- * // Recommendation is to use strong reference for async operations
- * const myFooStrong = myFooWeak.getStrong();
- * await doSomethingWithFoo(myFooStrong.getWeak()); // will never be freed while awaiting
- * // now we free
- * myFooStrong.free();
- *
- * ```
- *
- * ## Assigning to Erc
- * Each `Erc` instance should only ever have one external reference. So you should not
- * assign to an `Erc` variable directly:
- * ```typescript
- * // DO NOT DO THIS
- * let myFoo = makeFooErc(createFoo());
- * myFoo = makeFooErc(createFoo()); // previous Erc is overriden without proper clean up
- * ```
- *
- * If you want to attach a new value to an existing `Erc`, use the `assign` method:
- * ```typescript
- * const myFoo = makeFooErc(createFoo());
- * myFoo.assign(createFoo()); // previous Erc is freed, and the new one is assigned
- * myFoo.free(); // new one is freed
- * ```
- * The example above does not cause leaks, since the previous Erc is freed
- *
- * However, if you call assign with the value of another `Erc`, it will cause memory
- * issues:
- * ```typescript
- * // DO NOT DO THIS
- * const myFoo1 = makeFooErc(createFoo());
- * const myFoo2 = makeFooErc(createFoo());
- * myFoo1.assign(myFoo2.value); // myFoo1 is freed, and myFoo2 is assigned
- * // BAD: now both myFoo1 and myFoo2 references the same object, but the ref count is 1
- * myFoo1.free(); // no issue here, object is freed, but myFoo2 now holds a dangling pointer
- * myFoo2.free(); // double free!
- *
- * // The correct way to do this is to use `take`:
- * const myFoo1 = makeFooErc(createFoo());
- * const myFoo2 = makeFooErc(createFoo());
- * myFoo1.assign(myFoo2.take()); // myFoo1 is freed, and myFoo2 is assigned, myFoo2 is empty
- * myFoo1.free(); // no issue here, object is freed
- * // myFoo2 is empty, so calling free() has no effect
- * ```
- *
- * Assign also works if both `Erc` are 2 references of the same object:
- * ```typescript
- * const myFoo1 = makeFooErc(createFoo()); // ref count is 1
- * const myFoo2 = myFoo1.getStrong(); // ref count is 2
- * myFoo1.assign(myFoo2.take()); // frees old value, ref count is 1
- *
- * // This also works:
- * const myFoo1 = makeFooErc(createFoo()); // ref count is 1
- * myFoo1.assign(myFoo1.take()); // take() makes myFoo1 empty, so assign() doesn't free it
- *
- * // DO NOT DO THIS:
- * 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,
-    free,
-    addRef,
-}: ErcTypeConstructor<TName, TRepr>): ((value: TRepr | undefined) => Erc<TName, TRepr>) => {
-    const createStrongRef = (value: TRepr | undefined): Erc<TName, TRepr> => {
-        let weakRef: (ErcRef<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: () => {
-                    if (weak.value === undefined) {
-                        return createStrongRef(undefined);
-                    }
-                    return createStrongRef(addRef(weak.value));
-                },
-            };
-            return weak;
-        };
-        const erc = {
-            type: marker,
-            value,
-            free: () => {
-                if (erc.value !== undefined) {
-                    invalidateWeakRef();
-                    free(erc.value);
-                    erc.value = undefined;
-                }
-            },
-            assign: (newValue: TRepr | undefined) => {
-                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: () => {
-                if (erc.value === undefined) {
-                    return createStrongRef(undefined);
-                }
-                return createStrongRef(addRef(erc.value));
-            },
-        };
-        return erc;
-    };
-    return createStrongRef;
-};

package/src/pref/dark.ts

@@ -1,151 +0,0 @@
-import { persist } from "../memory/persist.ts";
-import { injectStyle } from "./inject_style.ts";
-
-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
- *
- * If `window.matchMedia` is not available, it will return `false`
- */
-export const prefersDarkMode = (): boolean => {
-    return !!globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches;
-};
-
-/** Value for the `color-scheme` CSS property */
-export type ColorScheme = "light" | "dark";
-/** Option for initializing dark mode */
-export type DarkOptions = {
-    /**
-     * Initial value for dark mode
-     *
-     * If not set, it will default to calling `prefersDarkMode()`.
-     *
-     * If `persist` is `true`, it will also check the value from localStorage
-     */
-    initial?: boolean;
-    /** Persist the dark mode preference to localStorage */
-    persist?: boolean;
-    /**
-     * The selector to set `color-scheme` property
-     *
-     * Defaults to `:root`. If set to empty string, CSS will not be updated
-     */
-    selector?: string;
-};
-
-/**
- * Init Dark mode wrappers
- *
- * ## Detect user preference
- * User preference is detected with `matchMedia` API, if available.
- * ```typescript
- * import { prefersDarkMode } from "@pistonite/pure/dark";
- *
- * console.log(prefersDarkMode());
- * ```
- *
- * ## Global dark mode state
- * `initDark` initializes the dark mode state.
- * ```typescript
- * import { initDark, isDark, setDark, addDarkSubscriber } from "@pistonite/pure/dark";
- *
- * initDark();
- * console.log(isDark());
- *
- * addDarkSubscriber((dark) => { console.log("Dark mode changed: ", dark); });
- * setDark(true); // will trigger the subscriber
- * ```
- *
- * ## Use with React
- * A React hook is provided in the [`pure-react`](https://jsr.io/@pistonite/pure-react/doc/pref) package
- * to get the dark mode state from React components.
- *
- * Use `setDark` to change the dark mode state from React compoenents like you would from anywhere else.
- *
- * ## Persisting to localStorage
- * You can persist the dark mode preference to by passing `persist: true` to `initDark`.
- * This will make `initDark` also load the preference from localStorage.
- * ```typescript
- * import { initDark } from "@pistonite/pure/dark";
- *
- * initDark({ persist: true });
- * ```
- *
- * ## Setting `color-scheme` CSS property
- * The `color-scheme` property handles dark mode for native components like buttons
- * and scrollbars. By default, `initDark` will handle setting this property for the `:root` selector.
- * You can override this by passing a `selector` option.
- * ```typescript
- * import { initDark } from "@pistonite/pure/dark";
- *
- * // will set `.my-app { color-scheme: dark }`
- * initDark({ selector: ".my-app" });
- * ```
- */
-export const initDark = (options: DarkOptions = {}): void => {
-    const _dark = options.initial || prefersDarkMode();
-
-    const selector = options.selector ?? ":root";
-    if (selector) {
-        // notify immediately to update the style initially
-        addDarkSubscriber((dark: boolean) => {
-            updateStyle(dark, selector);
-        }, true /* notify */);
-    }
-
-    if (options.persist) {
-        dark.init(_dark);
-    } else {
-        dark.disable();
-        dark.set(_dark);
-    }
-};
-
-/**
- * Clears the persisted dark mode preference
- *
- * If you are doing this, you should probably call `setDark`
- * with `prefersDarkMode()` or some initial value immediately before this,
- * so the current dark mode is set to user's preferred mode.
- *
- * Note if `persist` is `true` when initializing,
- * subsequence `setDark` calls will still persist the value.
- */
-export const clearPersistedDarkPerference = (): void => {
-    dark.clear();
-};
-
-/**
- * Gets the current value of dark mode
- */
-export const isDark = (): boolean => dark.get();
-
-/**
- * Set the value of dark mode
- */
-export const setDark = (value: boolean): void => {
-    dark.set(value);
-};
-/**
- * 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) => {
-    return dark.subscribe(subscriber, notifyImmediately);
-};
-
-const updateStyle = (dark: boolean, selector: string) => {
-    const text = `${selector} { color-scheme: ${dark ? "dark" : "light"}; }`;
-    injectStyle("pure-pref-dark", text);
-};

package/src/pref/device.ts

@@ -1,118 +0,0 @@
-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

@@ -1,13 +0,0 @@
-/**
- * # pure/pref
- * Preference utilities (things like locale and theme).
- *
- * These deal with raw CSS and DOM API, and is probably not
- * very useful outside of browser environment.
- *
- * @module
- */
-export * from "./dark.ts";
-export * from "./inject_style.ts";
-export * from "./locale.ts";
-export * from "./device.ts";

package/src/pref/inject_style.ts

@@ -1,22 +0,0 @@
-/**
- * Inject a css string into a style tag identified by the id
- *
- * Will remove the old style tag(s) if exist
- */
-export function injectStyle(id: string, style: string) {
-    const styleTags = document.querySelectorAll(`style[data-inject="${id}"]`);
-    if (styleTags.length !== 1) {
-        const styleTag = document.createElement("style");
-        styleTag.setAttribute("data-inject", id);
-        styleTag.innerText = style;
-        document.head.appendChild(styleTag);
-        setTimeout(() => {
-            styleTags.forEach((tag) => tag.remove());
-        }, 0);
-    } else {
-        const e = styleTags[0] as HTMLStyleElement;
-        if (e.innerText !== style) {
-            e.innerText = style;
-        }
-    }
-}