@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Function.d.ts

@@ -10,32 +10,36 @@
  * ### Example
  *
  * ```ts
+ * import { exhaustiveCheck } from "@evolu/common";
+ *
  * type Color = "red" | "green" | "blue";
+ * const handled: Array<string> = [];
  *
  * const handleColor = (color: Color): void => {
  *   switch (color) {
  *     case "red":
- *       console.log("Handling red");
+ *       handled.push("Handling red");
  *       break;
  *     case "green":
- *       console.log("Handling green");
+ *       handled.push("Handling green");
  *       break;
  *     case "blue":
- *       console.log("Handling blue");
+ *       handled.push("Handling blue");
  *       break;
  *     default:
- *       exhaustiveCheck(color); // Ensures all cases are handled
+ *       exhaustiveCheck(color);
  *   }
  * };
+ *
+ * handleColor("blue");
+ * expect(handled).toEqual(["Handling blue"]);
  * ```
  *
  * Use this primarily in side-effect switches (`void` branches). For
  * value-producing switches, TypeScript can enforce exhaustiveness without a
- * `default` branch.
- *
- * ### Example
+ * `default` branch in either of the following styles.
  *
- * Return from each case for value-producing switches.
+ * ### Return from every case
  *
  * ```ts
  * type Color = "red" | "green" | "blue";
@@ -50,11 +54,11 @@
  *       return "#0000ff";
  *   }
  * };
- * ```
  *
- * ### Example
+ * expect(colorToHex("green")).toBe("#00ff00");
+ * ```
  *
- * Use assignment + no `default` to get exhaustiveness by definite assignment.
+ * ### Assign in every case
  *
  * ```ts
  * type Input =
@@ -62,7 +66,7 @@
  *   | { readonly type: "Query" }
  *   | { readonly type: "Export" };
  *
- * const onInput = (input: Input): void => {
+ * const inputToKind = (input: Input): "A" | "B" | "C" => {
  *   let result: "A" | "B" | "C";
  *
  *   switch (input.type) {
@@ -77,12 +81,10 @@
  *       break;
  *   }
  *
- *   handleKind(result);
+ *   return result;
  * };
  *
- * const handleKind = (kind: "A" | "B" | "C"): void => {
- *   console.log(kind);
- * };
+ * expect(inputToKind({ type: "Query" })).toBe("B");
  * ```
  */
 export declare const exhaustiveCheck: (value: never) => never;
@@ -95,71 +97,128 @@ export declare const exhaustiveCheck: (value: never) => never;
  * ### Example
  *
  * ```ts
- * const values = [1, 2, 3];
- * const same = values.map(identity); // [1, 2, 3]
+ * import { identity } from "@evolu/common";
  *
+ * const values = [1, 2, 3];
+ * const object = { value: 1 };
  * const getTransform = (shouldDouble: boolean) =>
- *   shouldDouble ? (x: number) => x * 2 : identity;
+ *   shouldDouble ? (value: number) => value * 2 : identity;
+ *
+ * expect(values.map(identity)).toEqual([1, 2, 3]);
+ * expect(identity(object)).toBe(object);
+ * expect(getTransform(false)(2)).toBe(2);
  * ```
  */
 export declare const identity: <A>(a: A) => A;
 /**
- * A function that takes no arguments and returns a value of type T. Also known
- * as a thunk.
+ * Creates an object that follows JavaScript disposal semantics.
+ *
+ * The first argument is the object to make disposable. The returned object gets
+ * a disposal method and its functions are wrapped with a disposal guard. This
+ * is the JavaScript equivalent of .NET `ObjectDisposedException`: once an
+ * object has been disposed, calling its methods is a programmer error and
+ * should throw immediately instead of continuing with invalid state. Evolu
+ * asserts this invariant with the "Cannot use a disposed object." message.
+ *
+ * The second argument is an optional disposer. When provided, it is
+ * [moved](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DisposableStack/move)
+ * into the returned object, and the returned object's disposal method disposes
+ * it. Omit it when the object has no cleanup resources but still must become
+ * unusable after disposal, such as with reference count helpers where disposal
+ * enforces correct ownership tracking.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { disposable } from "@evolu/common";
+ *
+ * let cleaned = false;
+ * const createResource = () => {
+ *   using disposer = new DisposableStack();
+ *   disposer.defer(() => {
+ *     cleaned = true;
+ *   });
+ *   return disposable({ read: () => "ready" }, disposer);
+ * };
+ *
+ * const resource = createResource();
+ * expect(resource.read()).toBe("ready");
+ * resource[Symbol.dispose]();
+ *
+ * expect(cleaned).toBe(true);
+ * expect(() => resource.read()).toThrow("Cannot use a disposed object.");
+ * ```
+ */
+export declare function disposable<T extends object>(value: T extends Disposable ? Omit<T, typeof Symbol.dispose> : T, disposer?: DisposableStack): T extends Disposable ? T : T & Disposable;
+export declare function disposable<T extends object>(value: T extends AsyncDisposable ? Omit<T, typeof Symbol.asyncDispose> : T, disposer: AsyncDisposableStack): T extends AsyncDisposable ? T : T & AsyncDisposable;
+export declare const isDisposable: (value: unknown) => value is Disposable | AsyncDisposable;
+/**
+ * A function that takes no arguments and returns a value.
  *
  * Useful for:
  *
- * - Providing default callbacks (see {@link lazyVoid}, {@link lazyTrue}, etc.)
+ * - Providing default callbacks (see {@link constVoid}, {@link constTrue}, etc.)
  * - Delaying expensive operations until actually needed
  * - Deferring side effects so the callee controls when they run
  *
  * ### Example
  *
  * ```ts
- * // Default callback
- * const notify = (onDone: Lazy<void> = lazyVoid) => {
- *   onDone();
- * };
+ * import { constVoid, type Thunk } from "@evolu/common";
  *
- * // Delay computation
- * const getData: Lazy<Data> = () => compute();
- * const data = getData();
+ * const notify = (onDone: Thunk<void> = constVoid) => onDone();
+ * notify();
  *
- * // Defer side effects
- * const schedule = (job: Lazy<void>) => {
- *   queueMicrotask(job);
+ * let value = 0;
+ * const compute: Thunk<number> = () => ++value;
+ * const jobs: Array<Thunk<void>> = [];
+ * const schedule = (job: Thunk<void>): void => {
+ *   jobs.push(job);
  * };
- * schedule(() => logMetric("loaded"));
+ * schedule(() => {
+ *   value += 10;
+ * });
+ *
+ * const computed = compute();
+ * jobs.shift()?.();
+ * expect(computed).toBe(1);
+ * expect(value).toBe(11);
  * ```
  */
-export type Lazy<T> = () => T;
+export type Thunk<T> = () => T;
 /**
- * Creates a {@link Lazy} from a precomputed value.
+ * Creates a {@link Thunk} that always returns a precomputed value.
  *
- * Use when the value is expensive to compute and want to compute it once at
+ * Use when the value is expensive to compute and you want to compute it once at
  * definition time rather than on every call.
  *
  * ### Example
  *
  * ```ts
- * // Computed once at definition, returned on every call
- * const getConfig = lazy(parseConfig(rawConfig));
+ * import { constant } from "@evolu/common";
+ *
+ * let version = 0;
+ * const readConfig = () => ({ version: ++version });
+ * const getConstantConfig = constant(readConfig());
+ * const getFreshConfig = () => readConfig();
  *
- * // vs. computed on every call
- * const getConfig = () => parseConfig(rawConfig);
+ * expect(getConstantConfig()).toBe(getConstantConfig());
+ * expect(getConstantConfig().version).toBe(1);
+ * expect(getFreshConfig().version).toBe(2);
+ * expect(getFreshConfig().version).toBe(3);
  * ```
  */
-export declare const lazy: <T>(value: T) => Lazy<T>;
-/** A {@link Lazy} that returns `true`. */
-export declare const lazyTrue: Lazy<true>;
-/** A {@link Lazy} that returns `false`. */
-export declare const lazyFalse: Lazy<false>;
-/** A {@link Lazy} that returns `null`. */
-export declare const lazyNull: Lazy<null>;
-/** A {@link Lazy} that returns `undefined`. */
-export declare const lazyUndefined: Lazy<undefined>;
-/** A {@link Lazy} that returns `undefined` for void callbacks. */
-export declare const lazyVoid: Lazy<void>;
+export declare const constant: <T>(value: T) => Thunk<T>;
+/** A {@link Thunk} that returns `true`. */
+export declare const constTrue: Thunk<true>;
+/** A {@link Thunk} that returns `false`. */
+export declare const constFalse: Thunk<false>;
+/** A {@link Thunk} that returns `null`. */
+export declare const constNull: Thunk<null>;
+/** A {@link Thunk} that returns `undefined`. */
+export declare const constUndefined: Thunk<undefined>;
+/** A {@link Thunk} that returns `undefined` for void callbacks. */
+export declare const constVoid: Thunk<void>;
 /**
  * Development placeholder that always throws.
  *
@@ -170,17 +229,19 @@ export declare const lazyVoid: Lazy<void>;
  * ### Example
  *
  * ```ts
- * // Type inferred from return type annotation
- * const fetchUser = (id: UserId): Result<User, FetchError> => todo();
+ * import { todo } from "@evolu/common";
  *
- * expectTypeOf(fetchUser).returns.toEqualTypeOf<
- *   Result<User, FetchError>
- * >();
+ * interface Config {
+ *   readonly theme: string;
+ * }
  *
- * // Explicit generic when no return type
+ * const getCount = (): number => todo();
  * const getConfig = () => todo<Config>();
  *
- * expectTypeOf(getConfig).returns.toEqualTypeOf<Config>();
+ * expectTypeOf<
+ *   [ReturnType<typeof getCount>, ReturnType<typeof getConfig>]
+ * >().toEqualTypeOf<[number, Config]>();
+ * expect(getCount).toThrow("not yet implemented");
  * ```
  */
 export declare const todo: <T>() => T;

package/dist/src/Function.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Function.d.ts","sourceRoot":"","sources":["../../src/Function.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,KAAK,KAAG,KAE9C,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,GAAG,CAAC,KAAG,CAAM,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,GACd,CAAC,EAAE,OAAO,CAAC,KAAG,IAAI,CAAC,CAAC,CAEd,CAAC;AAEV,0CAA0C;AAC1C,eAAO,MAAM,QAAQ,EAAE,IAAI,CAAC,IAAI,CAA4B,CAAC;AAE7D,2CAA2C;AAC3C,eAAO,MAAM,SAAS,EAAE,IAAI,CAAC,KAAK,CAA6B,CAAC;AAEhE,0CAA0C;AAC1C,eAAO,MAAM,QAAQ,EAAE,IAAI,CAAC,IAAI,CAA4B,CAAC;AAE7D,+CAA+C;AAC/C,eAAO,MAAM,aAAa,EAAE,IAAI,CAAC,SAAS,CAAiC,CAAC;AAE5E,kEAAkE;AAClE,eAAO,MAAM,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAiB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,IAAI,GAAI,CAAC,OAAK,CAE1B,CAAC"}
+{"version":3,"file":"Function.d.ts","sourceRoot":"","sources":["../../src/Function.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,eAAe,UAAW,KAAK,KAAG,KAE9C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,KAAK,CAAC,KAAG,CAAM,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,CAAC,SAAS,UAAU,GAAG,IAAI,CAAC,CAAC,EAAE,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAChE,QAAQ,CAAC,EAAE,eAAe,GACzB,CAAC,SAAS,UAAU,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC;AAC7C,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,CAAC,SAAS,eAAe,GAAG,IAAI,CAAC,CAAC,EAAE,OAAO,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,EAC1E,QAAQ,EAAE,oBAAoB,GAC7B,CAAC,SAAS,eAAe,GAAG,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC;AA2BvD,eAAO,MAAM,YAAY,UAChB,OAAO,KACb,KAAK,IAAI,UAAU,GAAG,eAOxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,QAAQ,GAClB,CAAC,SAAS,CAAC,KAAG,KAAK,CAAC,CAAC,CAEf,CAAC;AAEV,2CAA2C;AAC3C,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,IAAI,CAAgC,CAAC;AAEnE,4CAA4C;AAC5C,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,KAAK,CAAiC,CAAC;AAEtE,2CAA2C;AAC3C,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,IAAI,CAAgC,CAAC;AAEnE,gDAAgD;AAChD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,SAAS,CACT,CAAC;AAEpC,mEAAmE;AACnE,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,IAAI,CAAkB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,eAAO,MAAM,IAAI,GAAI,CAAC,OAAK,CAE1B,CAAC"}

package/dist/src/Function.js

@@ -3,6 +3,8 @@
  *
  * @module
  */
+import { assertNotDisposed } from "./Assert.js";
+import { isFunction } from "./Object.js";
 /**
  * Helper function to ensure exhaustive matching in a switch statement. Throws
  * an error if an unhandled case is encountered.
@@ -10,32 +12,36 @@
  * ### Example
  *
  * ```ts
+ * import { exhaustiveCheck } from "@evolu/common";
+ *
  * type Color = "red" | "green" | "blue";
+ * const handled: Array<string> = [];
  *
  * const handleColor = (color: Color): void => {
  *   switch (color) {
  *     case "red":
- *       console.log("Handling red");
+ *       handled.push("Handling red");
  *       break;
  *     case "green":
- *       console.log("Handling green");
+ *       handled.push("Handling green");
  *       break;
  *     case "blue":
- *       console.log("Handling blue");
+ *       handled.push("Handling blue");
  *       break;
  *     default:
- *       exhaustiveCheck(color); // Ensures all cases are handled
+ *       exhaustiveCheck(color);
  *   }
  * };
+ *
+ * handleColor("blue");
+ * expect(handled).toEqual(["Handling blue"]);
  * ```
  *
  * Use this primarily in side-effect switches (`void` branches). For
  * value-producing switches, TypeScript can enforce exhaustiveness without a
- * `default` branch.
- *
- * ### Example
+ * `default` branch in either of the following styles.
  *
- * Return from each case for value-producing switches.
+ * ### Return from every case
  *
  * ```ts
  * type Color = "red" | "green" | "blue";
@@ -50,11 +56,11 @@
  *       return "#0000ff";
  *   }
  * };
- * ```
  *
- * ### Example
+ * expect(colorToHex("green")).toBe("#00ff00");
+ * ```
  *
- * Use assignment + no `default` to get exhaustiveness by definite assignment.
+ * ### Assign in every case
  *
  * ```ts
  * type Input =
@@ -62,7 +68,7 @@
  *   | { readonly type: "Query" }
  *   | { readonly type: "Export" };
  *
- * const onInput = (input: Input): void => {
+ * const inputToKind = (input: Input): "A" | "B" | "C" => {
  *   let result: "A" | "B" | "C";
  *
  *   switch (input.type) {
@@ -77,12 +83,10 @@
  *       break;
  *   }
  *
- *   handleKind(result);
+ *   return result;
  * };
  *
- * const handleKind = (kind: "A" | "B" | "C"): void => {
- *   console.log(kind);
- * };
+ * expect(inputToKind({ type: "Query" })).toBe("B");
  * ```
  */
 export const exhaustiveCheck = (value) => {
@@ -97,41 +101,78 @@ export const exhaustiveCheck = (value) => {
  * ### Example
  *
  * ```ts
- * const values = [1, 2, 3];
- * const same = values.map(identity); // [1, 2, 3]
+ * import { identity } from "@evolu/common";
  *
+ * const values = [1, 2, 3];
+ * const object = { value: 1 };
  * const getTransform = (shouldDouble: boolean) =>
- *   shouldDouble ? (x: number) => x * 2 : identity;
+ *   shouldDouble ? (value: number) => value * 2 : identity;
+ *
+ * expect(values.map(identity)).toEqual([1, 2, 3]);
+ * expect(identity(object)).toBe(object);
+ * expect(getTransform(false)(2)).toBe(2);
  * ```
  */
 export const identity = (a) => a;
+export function disposable(value, disposer = null) {
+    const mutableValue = value;
+    const ownedDisposer = disposer?.move() ?? new DisposableStack();
+    for (const [key, property] of Object.entries(value)) {
+        if (!isFunction(property))
+            continue;
+        mutableValue[key] = (...args) => {
+            assertNotDisposed(ownedDisposer);
+            return property(...args);
+        };
+    }
+    if (ownedDisposer instanceof AsyncDisposableStack) {
+        value[Symbol.asyncDispose] = () => ownedDisposer.disposeAsync();
+    }
+    else {
+        value[Symbol.dispose] = () => ownedDisposer.dispose();
+    }
+    return value;
+}
+export const isDisposable = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return (isFunction(value[Symbol.dispose]) ||
+        isFunction(value[Symbol.asyncDispose]));
+};
 /**
- * Creates a {@link Lazy} from a precomputed value.
+ * Creates a {@link Thunk} that always returns a precomputed value.
  *
- * Use when the value is expensive to compute and want to compute it once at
+ * Use when the value is expensive to compute and you want to compute it once at
  * definition time rather than on every call.
  *
  * ### Example
  *
  * ```ts
- * // Computed once at definition, returned on every call
- * const getConfig = lazy(parseConfig(rawConfig));
+ * import { constant } from "@evolu/common";
+ *
+ * let version = 0;
+ * const readConfig = () => ({ version: ++version });
+ * const getConstantConfig = constant(readConfig());
+ * const getFreshConfig = () => readConfig();
  *
- * // vs. computed on every call
- * const getConfig = () => parseConfig(rawConfig);
+ * expect(getConstantConfig()).toBe(getConstantConfig());
+ * expect(getConstantConfig().version).toBe(1);
+ * expect(getFreshConfig().version).toBe(2);
+ * expect(getFreshConfig().version).toBe(3);
  * ```
  */
-export const lazy = (value) => () => value;
-/** A {@link Lazy} that returns `true`. */
-export const lazyTrue = /*#__PURE__*/ lazy(true);
-/** A {@link Lazy} that returns `false`. */
-export const lazyFalse = /*#__PURE__*/ lazy(false);
-/** A {@link Lazy} that returns `null`. */
-export const lazyNull = /*#__PURE__*/ lazy(null);
-/** A {@link Lazy} that returns `undefined`. */
-export const lazyUndefined = /*#__PURE__*/ lazy(undefined);
-/** A {@link Lazy} that returns `undefined` for void callbacks. */
-export const lazyVoid = lazyUndefined;
+export const constant = (value) => () => value;
+/** A {@link Thunk} that returns `true`. */
+export const constTrue = /*#__PURE__*/ constant(true);
+/** A {@link Thunk} that returns `false`. */
+export const constFalse = /*#__PURE__*/ constant(false);
+/** A {@link Thunk} that returns `null`. */
+export const constNull = /*#__PURE__*/ constant(null);
+/** A {@link Thunk} that returns `undefined`. */
+export const constUndefined = 
+/*#__PURE__*/ constant(undefined);
+/** A {@link Thunk} that returns `undefined` for void callbacks. */
+export const constVoid = constUndefined;
 /**
  * Development placeholder that always throws.
  *
@@ -142,17 +183,19 @@ export const lazyVoid = lazyUndefined;
  * ### Example
  *
  * ```ts
- * // Type inferred from return type annotation
- * const fetchUser = (id: UserId): Result<User, FetchError> => todo();
+ * import { todo } from "@evolu/common";
  *
- * expectTypeOf(fetchUser).returns.toEqualTypeOf<
- *   Result<User, FetchError>
- * >();
+ * interface Config {
+ *   readonly theme: string;
+ * }
  *
- * // Explicit generic when no return type
+ * const getCount = (): number => todo();
  * const getConfig = () => todo<Config>();
  *
- * expectTypeOf(getConfig).returns.toEqualTypeOf<Config>();
+ * expectTypeOf<
+ *   [ReturnType<typeof getCount>, ReturnType<typeof getConfig>]
+ * >().toEqualTypeOf<[number, Config]>();
+ * expect(getCount).toThrow("not yet implemented");
  * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters