@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Object.d.ts

@@ -20,15 +20,20 @@ export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
  * Object.prototype` so it also works for plain objects coming from another
  * JavaScript realm.
  *
+ * TODO: deprecated Use `Object.is` from Type. Define a dedicated Type when
+ * another object domain is required.
+ *
  * ### Example
  *
  * ```ts
- * isPlainObject({}); // true
- * isPlainObject(Object.create(null)); // true
- * isPlainObject(new Date()); // false
- * isPlainObject(new (class Example {})()); // false
- * isPlainObject([]); // false
- * isPlainObject(null); // false
+ * import { isPlainObject } from "@evolu/common";
+ *
+ * expect(isPlainObject({})).toBe(true);
+ * expect(isPlainObject(Object.create(null))).toBe(true);
+ * expect(isPlainObject(new Date())).toBe(false);
+ * expect(isPlainObject(new (class Example {})())).toBe(false);
+ * expect(isPlainObject([])).toBe(false);
+ * expect(isPlainObject(null)).toBe(false);
  * ```
  */
 export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
@@ -38,9 +43,11 @@ export declare const isPlainObject: (value: unknown) => value is Record<string,
  * ### Example
  *
  * ```ts
- * isFunction(() => {}); // true
- * isFunction(function () {}); // true
- * isFunction({}); // false
+ * import { isFunction } from "@evolu/common";
+ *
+ * expect(isFunction(() => {})).toBe(true);
+ * expect(isFunction(function () {})).toBe(true);
+ * expect(isFunction({})).toBe(false);
  * ```
  */
 export declare const isFunction: (value: unknown) => value is globalThis.Function;
@@ -50,9 +57,11 @@ export declare const isFunction: (value: unknown) => value is globalThis.Functio
  * ### Example
  *
  * ```ts
- * isIterable([1, 2, 3]); // true
- * isIterable("abc"); // true
- * isIterable({}); // false
+ * import { isIterable } from "@evolu/common";
+ *
+ * expect(isIterable([1, 2, 3])).toBe(true);
+ * expect(isIterable("abc")).toBe(true);
+ * expect(isIterable({})).toBe(false);
  * ```
  */
 export declare const isIterable: (value: unknown) => value is Iterable<unknown>;
@@ -62,9 +71,20 @@ export declare const isIterable: (value: unknown) => value is Iterable<unknown>;
  * ### Example
  *
  * ```ts
- * type UserId = string & { readonly __brand: "UserId" };
- * const users = createRecord<UserId, string>();
- * const entries = objectToEntries(users); // [UserId, string][]
+ * import {
+ *   objectToEntries,
+ *   type Brand,
+ *   type ReadonlyRecord,
+ * } from "@evolu/common";
+ *
+ * type UserId = string & Brand<"UserId">;
+ *
+ * const userId = "u1" as UserId;
+ * const users: ReadonlyRecord<UserId, string> = { [userId]: "Alice" };
+ * const entries = objectToEntries(users);
+ *
+ * expectTypeOf(entries).toEqualTypeOf<ReadonlyArray<[UserId, string]>>();
+ * expect(entries).toEqual([[userId, "Alice"]]);
  * ```
  */
 export declare const objectToEntries: <T extends Record<string, any>>(record: T) => ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
@@ -78,11 +98,20 @@ type StringKeyOf<T> = Extract<keyof T, string>;
  * ### Example
  *
  * ```ts
- * type UserId = string & { readonly __brand: "UserId" };
+ * import {
+ *   objectFromEntries,
+ *   type Brand,
+ *   type ReadonlyRecord,
+ * } from "@evolu/common";
+ *
+ * type UserId = string & Brand<"UserId">;
  * const entries: ReadonlyArray<[UserId, string]> = [
  *   ["u1" as UserId, "Alice"],
  * ];
- * const users = objectFromEntries(entries); // ReadonlyRecord<UserId, string>
+ * const users = objectFromEntries(entries);
+ *
+ * expectTypeOf(users).toEqualTypeOf<ReadonlyRecord<UserId, string>>();
+ * expect(users).toEqual({ u1: "Alice" });
  * ```
  */
 export declare const objectFromEntries: <K extends string, V>(entries: Iterable<readonly [K, V]>) => ReadonlyRecord<K, V>;
@@ -95,11 +124,20 @@ export declare const objectFromEntries: <K extends string, V>(entries: Iterable<
  * ### Example
  *
  * ```ts
- * objectFrom(["en", "fr", "de"], loadTranslations);
- * // { en: Translations, fr: Translations, de: Translations }
+ * import { objectFrom, type ReadonlyRecord } from "@evolu/common";
  *
- * objectFrom(["trace", "debug", "log"], (level) => createHandler(level));
- * // { trace: Handler, debug: Handler, log: Handler }
+ * const translations = objectFrom(
+ *   ["en", "fr"] as const,
+ *   (locale): string => `Hello in ${locale}`,
+ * );
+ *
+ * expectTypeOf(translations).toEqualTypeOf<
+ *   ReadonlyRecord<"en" | "fr", string>
+ * >();
+ * expect(translations).toEqual({
+ *   en: "Hello in en",
+ *   fr: "Hello in fr",
+ * });
  * ```
  */
 export declare const objectFrom: <K extends string, V>(keys: ReadonlyArray<K>, getValue: (key: K) => V) => ReadonlyRecord<K, V>;
@@ -112,44 +150,123 @@ export declare const mapObject: <K extends string, V, U>(record: ReadonlyRecord<
 /** Conditionally excludes a property from an object. */
 export declare const excludeProp: <T extends object, K extends keyof T>(obj: T, prop: K, condition?: boolean) => typeof condition extends true ? T : Omit<T, K>;
 /**
- * Creates a prototype-less object typed as `Record<K, V>`.
+ * Creates a mutable Record.
+ *
+ * Use it to build a Record locally through mutation, avoiding repeated object
+ * spreads. Keep mutation scoped to the constructing function, and treat the
+ * completed Record as immutable after it leaves that scope. When a source is
+ * provided, its own enumerable properties are shallow-copied. Inherited and
+ * non-enumerable properties are not copied.
+ *
+ * The Record is created with `Object.create(null)`, so any string can be used
+ * as a key while it is being built. Missing keys such as `toString` and
+ * `constructor` do not resolve to inherited values, and assigning `__proto__`
+ * creates an own data property instead of changing the prototype.
+ *
+ * The null prototype makes dynamic construction safer, but it does not have to
+ * be preserved. Spreading the completed Record into an ordinary object is
+ * supported. Use {@link getOwnProp} when a lookup must read only own
+ * properties.
+ *
+ * For immutable empty application data, defaults, or placeholders, use
+ * {@link emptyRecord}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { createMutableRecord } from "@evolu/common";
  *
- * Use this function when you need a plain record without a prototype chain
- * (e.g. when keys are controlled by external sources) to avoid prototype
- * pollution and accidental collisions with properties like `__proto__`.
+ * const createValuesByKey = (
+ *   entries: ReadonlyArray<readonly [string, number]>,
+ * ): Readonly<Record<string, number>> => {
+ *   const valuesByKey = createMutableRecord<string, number>();
  *
- * Example:
+ *   for (const [key, value] of entries) {
+ *     valuesByKey[key] = value;
+ *   }
+ *
+ *   return valuesByKey;
+ * };
+ *
+ * expect(
+ *   createValuesByKey([
+ *     ["a", 1],
+ *     ["b", 2],
+ *   ]),
+ * ).toEqual({ a: 1, b: 2 });
+ * ```
+ *
+ * Note that TypeScript does not model an object's runtime prototype. A plain
+ * TypeScript Record exposes `Object.prototype` members even when the runtime
+ * object has a `null` prototype:
+ *
+ * ```ts
+ * const values = Object.create(null) as Record<string, number>;
+ *
+ * // TypeScript accepts the call, but `toString` is undefined at runtime.
+ * expect(() => values.toString()).toThrow(TypeError);
+ * ```
+ *
+ * `createMutableRecord` uses the same TypeScript Record representation.
  *
  * ```ts
- * const values = createRecord<string, SqliteValue>();
- * values["__proto__"] = someValue; // safe, no prototype pollution
+ * import { createMutableRecord } from "@evolu/common";
+ *
+ * const values = createMutableRecord<string, number>();
+ *
+ * // TypeScript accepts the call, but `toString` is undefined at runtime.
+ * expect(() => values.toString()).toThrow(TypeError);
  * ```
+ *
+ * In other words, treat the returned object as string-keyed data rather than
+ * calling inherited object methods through it.
  */
-export declare const createRecord: <K extends string = string, V = unknown>() => Record<K, V>;
+export declare function createMutableRecord<K extends string = string, V = unknown>(): Record<K, V>;
+export declare function createMutableRecord<T extends object>(source: T): {
+    -readonly [K in keyof T]: T[K];
+};
 /**
- * An empty readonly record.
+ * A shared frozen empty readonly Record.
  *
- * Use as a default or initial value to avoid allocating new empty records.
+ * Use it as an immutable empty value for defaults and placeholders instead of
+ * allocating a new empty object. Because the instance is shared, it is frozen
+ * to prevent accidental mutation.
+ *
+ * Use {@link createMutableRecord} to build a Record locally through mutation
+ * instead of repeated object spreads.
  *
  * @group Constants
  */
 export declare const emptyRecord: Readonly<Record<string, never>>;
 /**
- * Safely gets a property from a record, returning `undefined` if the key
- * doesn't exist.
+ * Gets an own property from a record, returning `undefined` if the key is
+ * missing or inherited.
  *
  * TypeScript's `Record<K, V>` type assumes all keys exist, but at runtime
- * accessing a non-existent key returns `undefined`. This helper provides proper
- * typing for that case without needing a type assertion.
+ * accessing a missing key returns `undefined`. This helper provides proper
+ * typing for that case without treating properties inherited from
+ * `Object.prototype` as record data.
  *
  * ### Example
  *
  * ```ts
- * const users: Record<string, User> = { alice: { name: "Alice" } };
- * const user = getProperty(users, "bob"); // User | undefined
+ * import { getOwnProp } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly name: string;
+ * }
+ *
+ * const users: Readonly<Record<string, User>> = {
+ *   alice: { name: "Alice" },
+ * };
+ * const user = getOwnProp(users, "bob");
+ *
+ * expectTypeOf(user).toEqualTypeOf<User | undefined>();
+ * expect(user).toBeUndefined();
+ * expect(getOwnProp(users, "toString")).toBeUndefined();
  * ```
  */
-export declare const getProperty: <K extends string, V>(record: ReadonlyRecord<K, V>, key: K) => V | undefined;
+export declare const getOwnProp: <K extends string, V>(record: ReadonlyRecord<K, V>, key: NoInfer<K>) => V | undefined;
 /**
  * A disposable wrapper around `URL.createObjectURL` that automatically revokes
  * the URL when disposed. Use with the `using` declaration for automatic
@@ -158,10 +275,13 @@ export declare const getProperty: <K extends string, V>(record: ReadonlyRecord<K
  * ### Example
  *
  * ```ts
+ * import { createObjectURL } from "@evolu/common";
+ *
  * const blob = new Blob(["hello"], { type: "text/plain" });
  * using objectUrl = createObjectURL(blob);
- * console.log(objectUrl.url); // blob:...
- * // URL.revokeObjectURL is automatically called when the scope ends
+ *
+ * expect(objectUrl.url).toMatch(/^blob:/);
+ * // URL.revokeObjectURL is automatically called when the scope ends.
  * ```
  *
  * This ensures the URL is always revoked when the scope ends, even if an error

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

@@ -1 +1 @@
-{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,aAAa,UACjB,OAAO,KACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAOjC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,UAAU,CAAC,QACnC,CAAC;AAE9B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAEA,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,UACnD,CAAC,KACR,aAAa,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CACkB,CAAC;AAGvE,KAAK,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,WAC1C,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KACjC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAwD,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,QACtC,aAAa,CAAC,CAAC,CAAC,YACZ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,KACtB,cAAc,CAAC,CAAC,EAAE,CAAC,CACyD,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,UACtC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,MACxB,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAC1B,cAAc,CAAC,CAAC,EAAE,CAAC,CAQrB,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,OACxD,CAAC,QACA,CAAC,cACK,OAAO,KAClB,OAAO,SAAS,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAM/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,CAAC,GAAG,OAAO,KACR,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAClB,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,MAAM,EAAE,CAAC,GACR;IAAE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAMtC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAGrD,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,UACpC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,OACvB,OAAO,CAAC,CAAC,CAAC,KACd,CAAC,GAAG,SAAmE,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,iEAAiE;AACjE,eAAO,MAAM,eAAe,SAAU,IAAI,KAAG,SAQ5C,CAAC"}

package/dist/src/Object.js

@@ -15,15 +15,20 @@
  * Object.prototype` so it also works for plain objects coming from another
  * JavaScript realm.
  *
+ * TODO: deprecated Use `Object.is` from Type. Define a dedicated Type when
+ * another object domain is required.
+ *
  * ### Example
  *
  * ```ts
- * isPlainObject({}); // true
- * isPlainObject(Object.create(null)); // true
- * isPlainObject(new Date()); // false
- * isPlainObject(new (class Example {})()); // false
- * isPlainObject([]); // false
- * isPlainObject(null); // false
+ * import { isPlainObject } from "@evolu/common";
+ *
+ * expect(isPlainObject({})).toBe(true);
+ * expect(isPlainObject(Object.create(null))).toBe(true);
+ * expect(isPlainObject(new Date())).toBe(false);
+ * expect(isPlainObject(new (class Example {})())).toBe(false);
+ * expect(isPlainObject([])).toBe(false);
+ * expect(isPlainObject(null)).toBe(false);
  * ```
  */
 export const isPlainObject = (value) => {
@@ -39,9 +44,11 @@ export const isPlainObject = (value) => {
  * ### Example
  *
  * ```ts
- * isFunction(() => {}); // true
- * isFunction(function () {}); // true
- * isFunction({}); // false
+ * import { isFunction } from "@evolu/common";
+ *
+ * expect(isFunction(() => {})).toBe(true);
+ * expect(isFunction(function () {})).toBe(true);
+ * expect(isFunction({})).toBe(false);
  * ```
  */
 export const isFunction = (value) => typeof value === "function";
@@ -51,9 +58,11 @@ export const isFunction = (value) => typeof value === "function";
  * ### Example
  *
  * ```ts
- * isIterable([1, 2, 3]); // true
- * isIterable("abc"); // true
- * isIterable({}); // false
+ * import { isIterable } from "@evolu/common";
+ *
+ * expect(isIterable([1, 2, 3])).toBe(true);
+ * expect(isIterable("abc")).toBe(true);
+ * expect(isIterable({})).toBe(false);
  * ```
  */
 export const isIterable = (value) => value != null &&
@@ -64,9 +73,20 @@ export const isIterable = (value) => value != null &&
  * ### Example
  *
  * ```ts
- * type UserId = string & { readonly __brand: "UserId" };
- * const users = createRecord<UserId, string>();
- * const entries = objectToEntries(users); // [UserId, string][]
+ * import {
+ *   objectToEntries,
+ *   type Brand,
+ *   type ReadonlyRecord,
+ * } from "@evolu/common";
+ *
+ * type UserId = string & Brand<"UserId">;
+ *
+ * const userId = "u1" as UserId;
+ * const users: ReadonlyRecord<UserId, string> = { [userId]: "Alice" };
+ * const entries = objectToEntries(users);
+ *
+ * expectTypeOf(entries).toEqualTypeOf<ReadonlyArray<[UserId, string]>>();
+ * expect(entries).toEqual([[userId, "Alice"]]);
  * ```
  */
 export const objectToEntries = (record) => Object.entries(record);
@@ -79,11 +99,20 @@ export const objectToEntries = (record) => Object.entries(record);
  * ### Example
  *
  * ```ts
- * type UserId = string & { readonly __brand: "UserId" };
+ * import {
+ *   objectFromEntries,
+ *   type Brand,
+ *   type ReadonlyRecord,
+ * } from "@evolu/common";
+ *
+ * type UserId = string & Brand<"UserId">;
  * const entries: ReadonlyArray<[UserId, string]> = [
  *   ["u1" as UserId, "Alice"],
  * ];
- * const users = objectFromEntries(entries); // ReadonlyRecord<UserId, string>
+ * const users = objectFromEntries(entries);
+ *
+ * expectTypeOf(users).toEqualTypeOf<ReadonlyRecord<UserId, string>>();
+ * expect(users).toEqual({ u1: "Alice" });
  * ```
  */
 export const objectFromEntries = (entries) => Object.fromEntries(entries);
@@ -96,11 +125,20 @@ export const objectFromEntries = (entries) => Object.fromEntries(entries);
  * ### Example
  *
  * ```ts
- * objectFrom(["en", "fr", "de"], loadTranslations);
- * // { en: Translations, fr: Translations, de: Translations }
- *
- * objectFrom(["trace", "debug", "log"], (level) => createHandler(level));
- * // { trace: Handler, debug: Handler, log: Handler }
+ * import { objectFrom, type ReadonlyRecord } from "@evolu/common";
+ *
+ * const translations = objectFrom(
+ *   ["en", "fr"] as const,
+ *   (locale): string => `Hello in ${locale}`,
+ * );
+ *
+ * expectTypeOf(translations).toEqualTypeOf<
+ *   ReadonlyRecord<"en" | "fr", string>
+ * >();
+ * expect(translations).toEqual({
+ *   en: "Hello in en",
+ *   fr: "Hello in fr",
+ * });
  * ```
  */
 export const objectFrom = (keys, getValue) => Object.fromEntries(keys.map((k) => [k, getValue(k)]));
@@ -124,46 +162,54 @@ export const excludeProp = (obj, prop, condition) => {
     const { [prop]: _, ...rest } = obj;
     return rest;
 };
+export function createMutableRecord(source) {
+    const record = Object.create(null);
+    return source === undefined ? record : Object.assign(record, source);
+}
 /**
- * Creates a prototype-less object typed as `Record<K, V>`.
+ * A shared frozen empty readonly Record.
  *
- * Use this function when you need a plain record without a prototype chain
- * (e.g. when keys are controlled by external sources) to avoid prototype
- * pollution and accidental collisions with properties like `__proto__`.
+ * Use it as an immutable empty value for defaults and placeholders instead of
+ * allocating a new empty object. Because the instance is shared, it is frozen
+ * to prevent accidental mutation.
  *
- * Example:
- *
- * ```ts
- * const values = createRecord<string, SqliteValue>();
- * values["__proto__"] = someValue; // safe, no prototype pollution
- * ```
- */
-export const createRecord = () => Object.create(null);
-/**
- * An empty readonly record.
- *
- * Use as a default or initial value to avoid allocating new empty records.
+ * Use {@link createMutableRecord} to build a Record locally through mutation
+ * instead of repeated object spreads.
  *
  * @group Constants
  */
 export const emptyRecord = 
-/*#__PURE__*/ createRecord();
+/*#__PURE__*/ Object.freeze(
+/*#__PURE__*/ createMutableRecord());
 /**
- * Safely gets a property from a record, returning `undefined` if the key
- * doesn't exist.
+ * Gets an own property from a record, returning `undefined` if the key is
+ * missing or inherited.
  *
  * TypeScript's `Record<K, V>` type assumes all keys exist, but at runtime
- * accessing a non-existent key returns `undefined`. This helper provides proper
- * typing for that case without needing a type assertion.
+ * accessing a missing key returns `undefined`. This helper provides proper
+ * typing for that case without treating properties inherited from
+ * `Object.prototype` as record data.
  *
  * ### Example
  *
  * ```ts
- * const users: Record<string, User> = { alice: { name: "Alice" } };
- * const user = getProperty(users, "bob"); // User | undefined
+ * import { getOwnProp } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly name: string;
+ * }
+ *
+ * const users: Readonly<Record<string, User>> = {
+ *   alice: { name: "Alice" },
+ * };
+ * const user = getOwnProp(users, "bob");
+ *
+ * expectTypeOf(user).toEqualTypeOf<User | undefined>();
+ * expect(user).toBeUndefined();
+ * expect(getOwnProp(users, "toString")).toBeUndefined();
  * ```
  */
-export const getProperty = (record, key) => (key in record ? record[key] : undefined);
+export const getOwnProp = (record, key) => (Object.hasOwn(record, key) ? record[key] : undefined);
 /** Creates a disposable {@link ObjectURL} for the given blob. */
 export const createObjectURL = (blob) => {
     const url = URL.createObjectURL(blob);

package/dist/src/Option.d.ts

@@ -9,23 +9,26 @@
  * ### Example
  *
  * ```ts
- * // A cache that can store any value, including null and undefined
+ * import { isNone, isSome, none, type Option, some } from "@evolu/common";
+ *
  * const cache = new Map<string, Option<unknown>>();
  *
  * const get = (key: string): Option<unknown> => cache.get(key) ?? none;
  *
- * cache.set("a", some(null)); // Stored null
- * cache.set("b", some(undefined)); // Stored undefined
+ * cache.set("a", some(null));
+ * cache.set("b", some(undefined));
  *
- * isSome(get("a")); // true — value is null
- * isSome(get("b")); // true — value is undefined
- * isNone(get("c")); // true — key doesn't exist
+ * const a = get("a");
+ * assert(isSome(a));
+ * expect(a.value).toBeNull();
+ * expect(isSome(get("b"))).toBe(true);
+ * expect(isNone(get("c"))).toBe(true);
  * ```
  *
  * @module
  */
 /** Optional value. */
-import type { Typed } from "./Type.js";
+import type { Typed } from "./Type.ts";
 /** Optional value. */
 export type Option<T> = Some<T> | None;
 /** Present value in an {@link Option}. */

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

@@ -1 +1 @@
-{"version":3,"file":"Option.d.ts","sourceRoot":"","sources":["../../src/Option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,sBAAsB;AACtB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEvC,sBAAsB;AACtB,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;AAEvC,0CAA0C;AAC1C,MAAM,WAAW,IAAI,CAAC,GAAG,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,MAAM,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,IAAK,SAAQ,KAAK,CAAC,MAAM,CAAC;CAAG;AAE9C;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,IAC3C,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEtC,8BAA8B;AAC9B,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,CAAC,CAGzC,CAAC;AAEH,oCAAoC;AACpC,eAAO,MAAM,IAAI,EAAE,IAAuB,CAAC;AAE3C,mCAAmC;AACnC,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,CAAC,KAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CACtC,CAAC;AAEzB,mCAAmC;AACnC,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,CAAC,KAAG,MAAM,IAAI,IAChC,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAC5B,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,KAC1B,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAyC,CAAC"}
+{"version":3,"file":"Option.d.ts","sourceRoot":"","sources":["../../src/Option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,sBAAsB;AACtB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEvC,sBAAsB;AACtB,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;AAEvC,0CAA0C;AAC1C,MAAM,WAAW,IAAI,CAAC,GAAG,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,MAAM,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,IAAK,SAAQ,KAAK,CAAC,MAAM,CAAC;CAAG;AAE9C;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,IAC3C,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEtC,8BAA8B;AAC9B,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,CAAC,KAAG,MAAM,CAAC,CAAC,CAGzC,CAAC;AAEH,oCAAoC;AACpC,eAAO,MAAM,IAAI,EAAE,IAAuB,CAAC;AAE3C,mCAAmC;AACnC,eAAO,MAAM,MAAM,GAAI,CAAC,UAAU,MAAM,CAAC,CAAC,CAAC,KAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CACtC,CAAC;AAEzB,mCAAmC;AACnC,eAAO,MAAM,MAAM,GAAI,CAAC,UAAU,MAAM,CAAC,CAAC,CAAC,KAAG,MAAM,IAAI,IAChC,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SACrB,CAAC,GAAG,IAAI,GAAG,SAAS,KAC1B,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAyC,CAAC"}

package/dist/src/Option.js

@@ -9,17 +9,20 @@
  * ### Example
  *
  * ```ts
- * // A cache that can store any value, including null and undefined
+ * import { isNone, isSome, none, type Option, some } from "@evolu/common";
+ *
  * const cache = new Map<string, Option<unknown>>();
  *
  * const get = (key: string): Option<unknown> => cache.get(key) ?? none;
  *
- * cache.set("a", some(null)); // Stored null
- * cache.set("b", some(undefined)); // Stored undefined
+ * cache.set("a", some(null));
+ * cache.set("b", some(undefined));
  *
- * isSome(get("a")); // true — value is null
- * isSome(get("b")); // true — value is undefined
- * isNone(get("c")); // true — key doesn't exist
+ * const a = get("a");
+ * assert(isSome(a));
+ * expect(a.value).toBeNull();
+ * expect(isSome(get("b"))).toBe(true);
+ * expect(isNone(get("c"))).toBe(true);
  * ```
  *
  * @module

package/dist/src/Order.d.ts

@@ -11,6 +11,9 @@
  * - Returns `-1` if `x` is less than `y`.
  * - Returns `0` if `x` is equal to `y`.
  * - Returns `1` if `x` is greater than `y`.
+ *
+ * An `Order` also defines equality. Use {@link eqFromOrder} to derive an
+ * {@link Eq}.
  */
 export type Order<in A> = (x: A, y: A) => Ordering;
 /**
@@ -25,10 +28,12 @@ export type Ordering = -1 | 0 | 1;
  * ### Example
  *
  * ```ts
+ * import { createOrder } from "@evolu/common";
+ *
  * const orderNumber = createOrder<number>((x, y) => x < y);
- * expect(orderNumber(1, 2)).toEqual(-1);
- * expect(orderNumber(2, 1)).toEqual(1);
- * expect(orderNumber(1, 1)).toEqual(0);
+ * expect(orderNumber(1, 2)).toBe(-1);
+ * expect(orderNumber(2, 1)).toBe(1);
+ * expect(orderNumber(1, 1)).toBe(0);
  * ```
  */
 export declare const createOrder: <A>(isLessThan: (x: A, y: A) => boolean) => Order<A>;
@@ -38,9 +43,10 @@ export declare const createOrder: <A>(isLessThan: (x: A, y: A) => boolean) => Or
  * ### Example
  *
  * ```ts
- * reverseOrder(orderNumber)(1, 2); // 1
- * reverseOrder(orderNumber)(2, 1); // -1
- * reverseOrder(orderNumber)(1, 1); // 0
+ * import { orderNumber, reverseOrder } from "@evolu/common";
+ *
+ * const descendingOrderNumber = reverseOrder(orderNumber);
+ * expect([3, 1, 2].toSorted(descendingOrderNumber)).toEqual([3, 2, 1]);
  * ```
  */
 export declare const reverseOrder: <A>(order: Order<A>) => Order<A>;
@@ -50,10 +56,9 @@ export declare const reverseOrder: <A>(order: Order<A>) => Order<A>;
  * ### Example
  *
  * ```ts
- * orderString("a", "b"); // -1
- * orderString("b", "a"); // 1
- * orderString("a", "a"); // 0
- * ["c", "b", "a"].toSorted(orderString); // ["a", "b", "c"]
+ * import { orderString } from "@evolu/common";
+ *
+ * expect(["c", "b", "a"].toSorted(orderString)).toEqual(["a", "b", "c"]);
  * ```
  */
 export declare const orderString: Order<string>;
@@ -63,13 +68,9 @@ export declare const orderString: Order<string>;
  * ### Example
  *
  * ```ts
- * orderNumber(1, 2); // -1
- * orderNumber(2, 1); // 1
- * orderNumber(1, 1); // 0
- * [2, 1, 3].toSorted(orderNumber); // [1, 2, 3]
- * reverseOrder(orderNumber)(1, 2); // 1
- * reverseOrder(orderNumber)(2, 1); // -1
- * reverseOrder(orderNumber)(1, 1); // 0
+ * import { orderNumber } from "@evolu/common";
+ *
+ * expect([2, 1, 3].toSorted(orderNumber)).toEqual([1, 2, 3]);
  * ```
  */
 export declare const orderNumber: Order<number>;
@@ -79,10 +80,9 @@ export declare const orderNumber: Order<number>;
  * ### Example
  *
  * ```ts
- * orderBigInt(1n, 2n); // -1
- * orderBigInt(2n, 1n); // 1
- * orderBigInt(1n, 1n); // 0
- * [2n, 1n, 3n].toSorted(orderBigInt); // [1n, 2n, 3n]
+ * import { orderBigInt } from "@evolu/common";
+ *
+ * expect([2n, 1n, 3n].toSorted(orderBigInt)).toEqual([1n, 2n, 3n]);
  * ```
  */
 export declare const orderBigInt: Order<bigint>;