structuralLookup - API reference

API reference › @evolu/common › Lookup › structuralLookup

function structuralLookup<K>(key: Structural<K>): StructuralLookupKey;

Defined in: packages/common/src/Lookup.ts:381

Returns the structural lookup key for key.

Structural lookup keys are derived from JSON-like values plus Uint8Array. Equal structures produce the same lookup key even when they are different JavaScript instances. Primitive values use SameValue (Object.is), so NaN equals itself while 0 and -0 produce different keys. undefined values and sparse array holes are rejected rather than skipped.

The derived key is memoized by non-null object identity in a module-scoped WeakMap shared by all callers, so keys must be immutable.

Use this as a Lookup when logical equality should be based on structural value instead of reference identity.

Example

import {
  assertEqual,
  assertSame,
  createLookupMap,
  structuralLookup,
  type StructuralLookupKey,
} from "@evolu/common";

interface Filter {
  readonly table: string;
  readonly where: readonly [string, string];
}

const byFilter = createLookupMap<Filter, string, StructuralLookupKey>({
  lookup: structuralLookup,
});

const cachedFilter: Filter = {
  table: "todo",
  where: ["owner", "ada"],
};
const equivalentFilter: Filter = {
  where: ["owner", "ada"],
  table: "todo",
};
byFilter.set(cachedFilter, "cached");

assertEqual(byFilter.get(equivalentFilter), "cached");
assertSame(byFilter.getKey(equivalentFilter), cachedFilter);

Example

See