@thi.ng/bidir-index 1.1.19 → 1.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-16T11:11:14Z
+- **Last updated**: 2025-04-30T12:52:32Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,19 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [1.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/bidir-index@1.2.0) (2025-04-30)
+
+#### 🚀 Features
+
+- restructure pkg, add `encodeObject()` / `decodeObject()` ([e812cac](https://github.com/thi-ng/umbrella/commit/e812cac))
+  - split up source files
+  - add new encoding/decoding fns
+  - add tests
+- add iterator versions of object encoders/decoders ([f647d5c](https://github.com/thi-ng/umbrella/commit/f647d5c))
+  - add `encodeObjectIterator()`
+  - add `decodeObjectIterator()`
+  - add tests
+
 ## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/bidir-index@1.1.0) (2024-07-22)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 205 standalone projects, maintained as part
+> This is one of 206 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -20,6 +20,7 @@
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
+- [Basic usage example](#basic-usage-example)
 - [Authors](#authors)
 - [License](#license)
 
@@ -66,7 +67,7 @@ For Node.js REPL:
 const bi = await import("@thi.ng/bidir-index");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 657 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 854 bytes
 
 ## Dependencies
 
@@ -78,6 +79,43 @@ None
 
 TODO
 
+## Basic usage example
+
+```ts tangle:export/readme.ts
+import { defBidirIndex, encodeObject, decodeObject } from "@thi.ng/bidir-index";
+
+const index = defBidirIndex<string>();
+
+// given object keys are auto-indexed, array initialized with given default
+console.log(
+  encodeObject(index, { r: 1, g: 2, b: 3, a: 4 }, 0)
+);
+// [1, 2, 3, 4]
+
+// use custom default and without updating index
+console.log(
+  encodeObject(index, { b: 3, r: 1, g: 2 }, -1, false)
+);
+// [1, 2, 3, -1] (missing key `a` mapped to given default value)
+
+// decode with defaults/fallback
+console.log(
+  decodeObject(index, [255, 128, 64], { a: 1 })
+);
+// { r: 255, g: 128, b: 64, a: 1 }
+
+// add more keys to index (already known ones will be skipped)
+// returns array of mapped IDs for given keys
+index.addAll(["r", "g", "b", "a", "foo"]);
+// [0, 1, 2, 3, 4]
+
+// decoding will skip nullish values
+console.log(
+  decodeObject(index, [null, null, null, null, "bar"])
+);
+// { foo: "bar" }
+```
+
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

package/api.d.ts

@@ -0,0 +1,18 @@
+export interface SerializedBidirIndex<T> {
+    pairs: [T, number][];
+    nextID: number;
+}
+export interface BidirIndexOpts<T> {
+    /**
+     * Custom `key -> id` map implementation (e.g. {@link EquivMap} or
+     * {@link HashMap}). If omitted, a native JS `Map` will be used.
+     */
+    map: Map<T, number>;
+    /**
+     * Start ID for indexing new keys.
+     *
+     * @defaultValue 0
+     */
+    start: number;
+}
+//# sourceMappingURL=api.d.ts.map

package/bidir-index.d.ts

@@ -0,0 +1,135 @@
+import type { BidirIndexOpts, SerializedBidirIndex } from "./api.js";
+/**
+ * Bi-directional index to map arbitrary keys to numeric IDs and vice versa.
+ */
+export declare class BidirIndex<T> {
+    fwd: Map<T, number>;
+    rev: Map<number, T>;
+    nextID: number;
+    constructor(keys?: Iterable<T> | null, opts?: Partial<BidirIndexOpts<T>>);
+    get size(): number;
+    /**
+     * Yields same result as {@link BidirIndex.entries}.
+     */
+    [Symbol.iterator](): MapIterator<[T, number]>;
+    /**
+     * Returns iterator of `[key,id]` pairs.
+     */
+    entries(): MapIterator<[T, number]>;
+    /**
+     * Returns iterator of all indexed keys.
+     */
+    keys(): MapIterator<T>;
+    /**
+     * Returns iterator of all indexed IDs.
+     */
+    values(): MapIterator<number>;
+    /**
+     * Returns true if given `key` is known/indexed.
+     *
+     * @param key
+     */
+    has(key: T): boolean;
+    /**
+     * Returns true if given `id` has a corresponding known/indexed key.
+     *
+     * @param id
+     */
+    hasID(id: number): boolean;
+    /**
+     * Reverse lookup of {@link BidirIndex.getID}. Returns the matching ID for
+     * given `key` or undefined if the key is not known.
+     *
+     * @param key
+     */
+    get(key: T): number | undefined;
+    /**
+     * Reverse lookup of {@link BidirIndex.get}. Returns the matching key for
+     * given `id` or undefined if the ID is not known.
+     *
+     * @param id
+     */
+    getID(id: number): T | undefined;
+    /**
+     * Indexes given `key` and assigns & returns a new ID. If `key` is already
+     * known/indexed, returns its existing ID.
+     *
+     * @param key
+     */
+    add(key: T): number;
+    /**
+     * Batch version of {@link BidirIndex.add}. Indexes all given keys and
+     * returns array of their corresponding IDs.
+     *
+     * @param keys
+     */
+    addAll(keys: Iterable<T>): number[];
+    /**
+     * Removes bi-directional mapping for given `key` from the index. Returns
+     * true if successful.
+     *
+     * @param key
+     */
+    delete(key: T): boolean;
+    /**
+     * Removes bi-directional mapping for given `id` from the index. Returns
+     * true if successful.
+     *
+     * @param id
+     */
+    deleteID(id: number): boolean;
+    /**
+     * Batch version of {@link BidirIndex.delete}.
+     *
+     * @param keys
+     */
+    deleteAll(keys: Iterable<T>): void;
+    /**
+     * Batch version of {@link BidirIndex.deleteID}.
+     *
+     * @param ids
+     */
+    deleteAllIDs(ids: Iterable<number>): void;
+    /**
+     * Returns array of IDs for all given keys. If `fail` is true (default:
+     * false), throws error if any of the given keys is unknown/unindexed (use
+     * {@link BidirIndex.add} or {@link BidirIndex.addAll} first).
+     *
+     * @param keys
+     * @param fail
+     */
+    getAll(keys: Iterable<T>, fail?: boolean): number[];
+    /**
+     * Returns array of matching keys for all given IDs. If `fail` is true
+     * (default: false), throws error if any of the given IDs is
+     * unknown/unindexed (use {@link BidirIndex.add} or
+     * {@link BidirIndex.addAll} first).
+     *
+     * @param ids
+     * @param fail
+     */
+    getAllIDs(ids: Iterable<number>, fail?: boolean): T[];
+    /**
+     * Returns a compact JSON serializable version of the index. Use
+     * {@link bidirIndexFromJSON} to instantiate an index from such a JSON
+     * serialization.
+     */
+    toJSON(): SerializedBidirIndex<T>;
+}
+/**
+ * Factory function wrapper for {@link BidirIndex}.
+ *
+ * @param keys
+ * @param opts
+ */
+export declare const defBidirIndex: <T>(keys?: Iterable<T>, opts?: Partial<BidirIndexOpts<T>>) => BidirIndex<T>;
+/**
+ * Instantiates a {@link BidirIndex} from given JSON serialization. The optional
+ * `map` arg can be used to provide a customized `key -> id` map implementation
+ * (same use as {@link BidirIndexOpts.map}).
+ *
+ * @param src
+ * @param map
+ */
+export declare const bidirIndexFromJSON: <T>(src: string | SerializedBidirIndex<T>, map?: Map<T, number>) => BidirIndex<T>;
+//# sourceMappingURL=bidir-index.d.ts.map

package/bidir-index.js

@@ -0,0 +1,204 @@
+class BidirIndex {
+  fwd;
+  rev;
+  nextID;
+  constructor(keys, opts = {}) {
+    this.nextID = opts.start || 0;
+    this.fwd = opts.map || /* @__PURE__ */ new Map();
+    this.rev = /* @__PURE__ */ new Map();
+    keys && this.addAll(keys);
+  }
+  get size() {
+    return this.fwd.size;
+  }
+  /**
+   * Yields same result as {@link BidirIndex.entries}.
+   */
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+  /**
+   * Returns iterator of `[key,id]` pairs.
+   */
+  entries() {
+    return this.fwd.entries();
+  }
+  /**
+   * Returns iterator of all indexed keys.
+   */
+  keys() {
+    return this.fwd.keys();
+  }
+  /**
+   * Returns iterator of all indexed IDs.
+   */
+  values() {
+    return this.fwd.values();
+  }
+  /**
+   * Returns true if given `key` is known/indexed.
+   *
+   * @param key
+   */
+  has(key) {
+    return this.fwd.has(key);
+  }
+  /**
+   * Returns true if given `id` has a corresponding known/indexed key.
+   *
+   * @param id
+   */
+  hasID(id) {
+    return this.rev.has(id);
+  }
+  /**
+   * Reverse lookup of {@link BidirIndex.getID}. Returns the matching ID for
+   * given `key` or undefined if the key is not known.
+   *
+   * @param key
+   */
+  get(key) {
+    return this.fwd.get(key);
+  }
+  /**
+   * Reverse lookup of {@link BidirIndex.get}. Returns the matching key for
+   * given `id` or undefined if the ID is not known.
+   *
+   * @param id
+   */
+  getID(id) {
+    return this.rev.get(id);
+  }
+  /**
+   * Indexes given `key` and assigns & returns a new ID. If `key` is already
+   * known/indexed, returns its existing ID.
+   *
+   * @param key
+   */
+  add(key) {
+    let id = this.fwd.get(key);
+    if (id === void 0) {
+      this.fwd.set(key, this.nextID);
+      this.rev.set(this.nextID, key);
+      id = this.nextID++;
+    }
+    return id;
+  }
+  /**
+   * Batch version of {@link BidirIndex.add}. Indexes all given keys and
+   * returns array of their corresponding IDs.
+   *
+   * @param keys
+   */
+  addAll(keys) {
+    const res = [];
+    for (let k of keys) {
+      res.push(this.add(k));
+    }
+    return res;
+  }
+  /**
+   * Removes bi-directional mapping for given `key` from the index. Returns
+   * true if successful.
+   *
+   * @param key
+   */
+  delete(key) {
+    return __delete(this.fwd, this.rev, key);
+  }
+  /**
+   * Removes bi-directional mapping for given `id` from the index. Returns
+   * true if successful.
+   *
+   * @param id
+   */
+  deleteID(id) {
+    return __delete(this.rev, this.fwd, id);
+  }
+  /**
+   * Batch version of {@link BidirIndex.delete}.
+   *
+   * @param keys
+   */
+  deleteAll(keys) {
+    for (let k of keys) this.delete(k);
+  }
+  /**
+   * Batch version of {@link BidirIndex.deleteID}.
+   *
+   * @param ids
+   */
+  deleteAllIDs(ids) {
+    for (let id of ids) this.deleteID(id);
+  }
+  /**
+   * Returns array of IDs for all given keys. If `fail` is true (default:
+   * false), throws error if any of the given keys is unknown/unindexed (use
+   * {@link BidirIndex.add} or {@link BidirIndex.addAll} first).
+   *
+   * @param keys
+   * @param fail
+   */
+  getAll(keys, fail = false) {
+    return __iterate(this.fwd, keys, fail);
+  }
+  /**
+   * Returns array of matching keys for all given IDs. If `fail` is true
+   * (default: false), throws error if any of the given IDs is
+   * unknown/unindexed (use {@link BidirIndex.add} or
+   * {@link BidirIndex.addAll} first).
+   *
+   * @param ids
+   * @param fail
+   */
+  getAllIDs(ids, fail = false) {
+    return __iterate(this.rev, ids, fail);
+  }
+  /**
+   * Returns a compact JSON serializable version of the index. Use
+   * {@link bidirIndexFromJSON} to instantiate an index from such a JSON
+   * serialization.
+   */
+  toJSON() {
+    return {
+      pairs: [...this.entries()],
+      nextID: this.nextID
+    };
+  }
+}
+const __delete = (fwd, rev, key) => {
+  const val = fwd.get(key);
+  if (val !== void 0) {
+    fwd.delete(key);
+    rev.delete(val);
+    return true;
+  }
+  return false;
+};
+const __iterate = (index, keys, fail) => {
+  const res = [];
+  for (let k of keys) {
+    const val = index.get(k);
+    if (val === void 0) {
+      if (fail) throw new Error(`unknwon key/ID: ${k}`);
+    } else {
+      res.push(val);
+    }
+  }
+  return res;
+};
+const defBidirIndex = (keys, opts) => new BidirIndex(keys, opts);
+const bidirIndexFromJSON = (src, map) => {
+  const $src = typeof src === "string" ? JSON.parse(src) : src;
+  const res = new BidirIndex(null, { map, start: $src.nextID });
+  $src.pairs.forEach(([k, id]) => {
+    res.fwd.set(k, id);
+    res.rev.set(id, k);
+  });
+  return res;
+};
+export {
+  BidirIndex,
+  bidirIndexFromJSON,
+  defBidirIndex
+};

package/encode.d.ts

@@ -0,0 +1,128 @@
+import type { BidirIndex } from "./bidir-index.js";
+/**
+ * Encodes given object into an array, using the given `index` to determine each
+ * key's value position. The array will be pre-filled with `defaultValue`.
+ * Unless `indexKeys` is disabled, the object's keys are first added to the
+ * index.
+ *
+ * @remarks
+ * Also see {@link decodeObject} for reverse operation.
+ *
+ * @example
+ * ```ts tangle:../export/encode-object.ts
+ * import { defBidirIndex, encodeObject } from "@thi.ng/bidir-index";
+ *
+ * const index = defBidirIndex<string>();
+ *
+ * console.log(
+ *   encodeObject(index, { r: 255, g: 128, b: 64, a: 1 }, 0)
+ * );
+ * // [255, 128, 64, 1]
+ *
+ * // encode without updating index
+ * console.log(
+ *   encodeObject(index, { b: 3, r: 1, g: 2 }, 0, false)
+ * );
+ * // [1, 2, 3, 0] (key `a` uses default)
+ * ```
+ *
+ * @param index
+ * @param obj
+ * @param defaultValue
+ * @param indexKeys
+ */
+export declare const encodeObject: <V, K extends string = string>(index: BidirIndex<K>, obj: Partial<Record<K, V>>, defaultValue: V, indexKeys?: boolean) => V[];
+/**
+ * Similar to {@link encodeObject}, but implemented as an iterator for
+ * processing multiple objects into a single flat iterable.
+ *
+ * @example
+ * ```ts tangle:../export/encode-object-iterator.ts
+ * import { defBidirIndex, encodeObjectIterator } from "@thi.ng/bidir-index";
+ *
+ * const index = defBidirIndex<string>();
+ *
+ * // source data objects
+ * const data = [
+ *   { r: 1, g: 2, b: 3},
+ *   { x: 4, y: 5, z: 6}
+ * ];
+ *
+ * // directly encode into a typedarray
+ * const buf = new Uint8Array(encodeObjectIterator(index, data, 0));
+ *
+ * console.log(buf);
+ * // Uint8Array(12) [ 1, 2, 3, 0, 0, 0, 0, 0, 0, 4, 5, 6 ]
+ * ```
+ *
+ * @param index
+ * @param objects
+ * @param defaultValue
+ * @param indexKeys
+ */
+export declare const encodeObjectIterator: <V, K extends string = string>(index: BidirIndex<K>, objects: Partial<Record<K, V>>[], defaultValue: V, indexKeys?: boolean) => Generator<V, void, unknown>;
+/**
+ * Reverse op of {@link encodeObject}. Takes an array of `values` and returns an
+ * object with values mapped to keys based on their indexed position. If the
+ * `values` array has a nullish value for a keyed index, the optionally provided
+ * `defaults` object will be used to obtain a value. The result object will only
+ * have keys with non-nullish values.
+ *
+ * @remarks
+ * Note: Irrespective of original key type used for this index instance, the
+ * keys in the result object will be strings.
+ *
+ * Also see {@link encodeObject}.
+ *
+ * @example
+ * ```ts tangle:../export/decode-object.ts
+ * import { defBidirIndex, decodeObject } from "@thi.ng/bidir-index";
+ *
+ * const index = defBidirIndex<string>();
+ * index.addAll(["r", "g", "b", "a", "foo"]);
+ *
+ * // decode with defaults/fallback
+ * console.log(
+ *   decodeObject(index, [255, 128, 64], { a: 1 })
+ * );
+ * // { r: 255, g: 128, b: 64, a: 1 } (key `foo` is omitted in result)
+ *
+ * console.log(
+ *   decodeObject(index, [null, null, null, null, "bar"])
+ * );
+ * // { foo: "bar" }
+ * ```
+ *
+ * @param values
+ * @param defaults
+ */
+export declare const decodeObject: <V, K extends string = string>(index: Iterable<[K, number]>, values: V[], defaults?: Partial<Record<K, V>>) => Partial<Record<K, V>>;
+/**
+ * Reverse op of {@link encodeObjectIterator}. An iterator which takes an array
+ * of encoded values and yields sequence of objects decoded via
+ * {@link decodeObject}.
+ *
+ * @example
+ * ```ts tangle:../export/decode-object-iterator.ts
+ * import { defBidirIndex, decodeObjectIterator } from "@thi.ng/bidir-index";
+ *
+ * const index = defBidirIndex<string>();
+ * index.addAll("rgbxyz");
+ *
+ * const data = [1, 2, 3, 0, 0, 0, 0, 0, 0, 4, 5, 6];
+ *
+ * for(let obj of decodeObjectIterator(index, data, 6)) {
+ *   console.log(obj);
+ * }
+ *
+ * // { r: 1, g: 2, b: 3, x: 0, y: 0, z: 0 }
+ * // { r: 0, g: 0, b: 0, x: 4, y: 5, z: 6 }
+ * ```
+ *
+ * @param index
+ * @param values
+ * @param size
+ * @param defaults
+ */
+export declare function decodeObjectIterator<V, K extends string = string>(index: Iterable<[K, number]>, values: V[], size: number, defaults?: Partial<Record<K, V>>): Generator<Partial<Record<K, V>>, void, unknown>;
+//# sourceMappingURL=encode.d.ts.map

package/encode.js

@@ -0,0 +1,37 @@
+const encodeObject = (index, obj, defaultValue, indexKeys = true) => {
+  const keys = Object.keys(obj);
+  const ids = indexKeys ? index.addAll(keys) : index.getAll(keys);
+  const res = new Array(index.size).fill(defaultValue);
+  for (let id of ids) {
+    const val = obj[index.getID(id)];
+    if (val != null) res[id] = val;
+  }
+  return res;
+};
+const encodeObjectIterator = function* (index, objects, defaultValue, indexKeys = true) {
+  if (indexKeys) {
+    for (let o of objects) index.addAll(Object.keys(o));
+  }
+  for (let o of objects) {
+    yield* encodeObject(index, o, defaultValue, false);
+  }
+};
+const decodeObject = (index, values, defaults) => {
+  const res = {};
+  for (let [k, id] of index) {
+    const val = values[id] ?? defaults?.[k];
+    if (val != null) res[k] = val;
+  }
+  return res;
+};
+function* decodeObjectIterator(index, values, size, defaults) {
+  for (let i = 0, num = values.length; i < num; i += size) {
+    yield decodeObject(index, values.slice(i, i + size), defaults);
+  }
+}
+export {
+  decodeObject,
+  decodeObjectIterator,
+  encodeObject,
+  encodeObjectIterator
+};

package/index.d.ts

@@ -1,151 +1,4 @@
-export interface SerializedBidirIndex<T> {
-    pairs: [T, number][];
-    nextID: number;
-}
-export interface BidirIndexOpts<T> {
-    /**
-     * Custom `key -> id` map implementation (e.g. {@link EquivMap} or
-     * {@link HashMap}). If omitted, a native JS `Map` will be used.
-     */
-    map: Map<T, number>;
-    /**
-     * Start ID for indexing new keys.
-     *
-     * @defaultValue 0
-     */
-    start: number;
-}
-/**
- * Bi-directional index to map arbitrary keys to numeric IDs and vice versa.
- */
-export declare class BidirIndex<T> {
-    fwd: Map<T, number>;
-    rev: Map<number, T>;
-    nextID: number;
-    constructor(keys?: Iterable<T> | null, opts?: Partial<BidirIndexOpts<T>>);
-    get size(): number;
-    /**
-     * Yields same result as {@link BidirIndex.entries}.
-     */
-    [Symbol.iterator](): MapIterator<[T, number]>;
-    /**
-     * Returns iterator of `[key,id]` pairs.
-     */
-    entries(): MapIterator<[T, number]>;
-    /**
-     * Returns iterator of all indexed keys.
-     */
-    keys(): MapIterator<T>;
-    /**
-     * Returns iterator of all indexed IDs.
-     */
-    values(): MapIterator<number>;
-    /**
-     * Returns true if given `key` is known/indexed.
-     *
-     * @param key
-     */
-    has(key: T): boolean;
-    /**
-     * Returns true if given `id` has a corresponding known/indexed key.
-     *
-     * @param id
-     */
-    hasID(id: number): boolean;
-    /**
-     * Reverse lookup of {@link BidirIndex.getID}. Returns the matching ID for
-     * given `key` or undefined if the key is not known.
-     *
-     * @param key
-     */
-    get(key: T): number | undefined;
-    /**
-     * Reverse lookup of {@link BidirIndex.get}. Returns the matching key for
-     * given `id` or undefined if the ID is not known.
-     *
-     * @param id
-     */
-    getID(id: number): T | undefined;
-    /**
-     * Indexes given `key` and assigns & returns a new ID. If `key` is already
-     * known/indexed, returns its existing ID.
-     *
-     * @param key
-     */
-    add(key: T): number;
-    /**
-     * Batch version of {@link BidirIndex.add}. Indexes all given keys and
-     * returns array of their corresponding IDs.
-     *
-     * @param keys
-     */
-    addAll(keys: Iterable<T>): number[];
-    /**
-     * Removes bi-directional mapping for given `key` from the index. Returns
-     * true if successful.
-     *
-     * @param key
-     */
-    delete(key: T): boolean;
-    /**
-     * Removes bi-directional mapping for given `id` from the index. Returns
-     * true if successful.
-     *
-     * @param id
-     */
-    deleteID(id: number): boolean;
-    /**
-     * Batch version of {@link BidirIndex.delete}.
-     *
-     * @param keys
-     */
-    deleteAll(keys: Iterable<T>): void;
-    /**
-     * Batch version of {@link BidirIndex.deleteID}.
-     *
-     * @param ids
-     */
-    deleteAllIDs(ids: Iterable<number>): void;
-    /**
-     * Returns array of IDs for all given keys. If `fail` is true (default:
-     * false), throws error if any of the given keys is unknown/unindexed (use
-     * {@link BidirIndex.add} or {@link BidirIndex.addAll} first).
-     *
-     * @param keys
-     * @param fail
-     */
-    getAll(keys: Iterable<T>, fail?: boolean): number[];
-    /**
-     * Returns array of matching keys for all given IDs. If `fail` is true
-     * (default: false), throws error if any of the given IDs is
-     * unknown/unindexed (use {@link BidirIndex.add} or
-     * {@link BidirIndex.addAll} first).
-     *
-     * @param ids
-     * @param fail
-     */
-    getAllIDs(ids: Iterable<number>, fail?: boolean): T[];
-    /**
-     * Returns a compact JSON serializable version of the index. Use
-     * {@link bidirIndexFromJSON} to instantiate an index from such a JSON
-     * serialization.
-     */
-    toJSON(): SerializedBidirIndex<T>;
-}
-/**
- * Factory function wrapper for {@link BidirIndex}.
- *
- * @param keys
- * @param opts
- */
-export declare const defBidirIndex: <T>(keys?: Iterable<T>, opts?: Partial<BidirIndexOpts<T>>) => BidirIndex<T>;
-/**
- * Instantiates a {@link BidirIndex} from given JSON serialization. The optional
- * `map` arg can be used to provide a customized `key -> id` map implementation
- * (same use as {@link BidirIndexOpts.map}).
- *
- * @param src
- * @param map
- */
-export declare const bidirIndexFromJSON: <T>(src: string | SerializedBidirIndex<T>, map?: Map<T, number>) => BidirIndex<T>;
+export * from "./api.js";
+export * from "./bidir-index.js";
+export * from "./encode.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,204 +1,3 @@
-class BidirIndex {
-  fwd;
-  rev;
-  nextID;
-  constructor(keys, opts = {}) {
-    this.nextID = opts.start || 0;
-    this.fwd = opts.map || /* @__PURE__ */ new Map();
-    this.rev = /* @__PURE__ */ new Map();
-    keys && this.addAll(keys);
-  }
-  get size() {
-    return this.fwd.size;
-  }
-  /**
-   * Yields same result as {@link BidirIndex.entries}.
-   */
-  [Symbol.iterator]() {
-    return this.entries();
-  }
-  /**
-   * Returns iterator of `[key,id]` pairs.
-   */
-  entries() {
-    return this.fwd.entries();
-  }
-  /**
-   * Returns iterator of all indexed keys.
-   */
-  keys() {
-    return this.fwd.keys();
-  }
-  /**
-   * Returns iterator of all indexed IDs.
-   */
-  values() {
-    return this.fwd.values();
-  }
-  /**
-   * Returns true if given `key` is known/indexed.
-   *
-   * @param key
-   */
-  has(key) {
-    return this.fwd.has(key);
-  }
-  /**
-   * Returns true if given `id` has a corresponding known/indexed key.
-   *
-   * @param id
-   */
-  hasID(id) {
-    return this.rev.has(id);
-  }
-  /**
-   * Reverse lookup of {@link BidirIndex.getID}. Returns the matching ID for
-   * given `key` or undefined if the key is not known.
-   *
-   * @param key
-   */
-  get(key) {
-    return this.fwd.get(key);
-  }
-  /**
-   * Reverse lookup of {@link BidirIndex.get}. Returns the matching key for
-   * given `id` or undefined if the ID is not known.
-   *
-   * @param id
-   */
-  getID(id) {
-    return this.rev.get(id);
-  }
-  /**
-   * Indexes given `key` and assigns & returns a new ID. If `key` is already
-   * known/indexed, returns its existing ID.
-   *
-   * @param key
-   */
-  add(key) {
-    let id = this.fwd.get(key);
-    if (id === void 0) {
-      this.fwd.set(key, this.nextID);
-      this.rev.set(this.nextID, key);
-      id = this.nextID++;
-    }
-    return id;
-  }
-  /**
-   * Batch version of {@link BidirIndex.add}. Indexes all given keys and
-   * returns array of their corresponding IDs.
-   *
-   * @param keys
-   */
-  addAll(keys) {
-    const res = [];
-    for (let k of keys) {
-      res.push(this.add(k));
-    }
-    return res;
-  }
-  /**
-   * Removes bi-directional mapping for given `key` from the index. Returns
-   * true if successful.
-   *
-   * @param key
-   */
-  delete(key) {
-    return __delete(this.fwd, this.rev, key);
-  }
-  /**
-   * Removes bi-directional mapping for given `id` from the index. Returns
-   * true if successful.
-   *
-   * @param id
-   */
-  deleteID(id) {
-    return __delete(this.rev, this.fwd, id);
-  }
-  /**
-   * Batch version of {@link BidirIndex.delete}.
-   *
-   * @param keys
-   */
-  deleteAll(keys) {
-    for (let k of keys) this.delete(k);
-  }
-  /**
-   * Batch version of {@link BidirIndex.deleteID}.
-   *
-   * @param ids
-   */
-  deleteAllIDs(ids) {
-    for (let id of ids) this.deleteID(id);
-  }
-  /**
-   * Returns array of IDs for all given keys. If `fail` is true (default:
-   * false), throws error if any of the given keys is unknown/unindexed (use
-   * {@link BidirIndex.add} or {@link BidirIndex.addAll} first).
-   *
-   * @param keys
-   * @param fail
-   */
-  getAll(keys, fail = false) {
-    return __iterate(this.fwd, keys, fail);
-  }
-  /**
-   * Returns array of matching keys for all given IDs. If `fail` is true
-   * (default: false), throws error if any of the given IDs is
-   * unknown/unindexed (use {@link BidirIndex.add} or
-   * {@link BidirIndex.addAll} first).
-   *
-   * @param ids
-   * @param fail
-   */
-  getAllIDs(ids, fail = false) {
-    return __iterate(this.rev, ids, fail);
-  }
-  /**
-   * Returns a compact JSON serializable version of the index. Use
-   * {@link bidirIndexFromJSON} to instantiate an index from such a JSON
-   * serialization.
-   */
-  toJSON() {
-    return {
-      pairs: [...this.entries()],
-      nextID: this.nextID
-    };
-  }
-}
-const __delete = (fwd, rev, key) => {
-  const val = fwd.get(key);
-  if (val !== void 0) {
-    fwd.delete(key);
-    rev.delete(val);
-    return true;
-  }
-  return false;
-};
-const __iterate = (index, keys, fail) => {
-  const res = [];
-  for (let k of keys) {
-    const val = index.get(k);
-    if (val === void 0) {
-      if (fail) throw new Error(`unknwon key/ID: ${k}`);
-    } else {
-      res.push(val);
-    }
-  }
-  return res;
-};
-const defBidirIndex = (keys, opts) => new BidirIndex(keys, opts);
-const bidirIndexFromJSON = (src, map) => {
-  const $src = typeof src === "string" ? JSON.parse(src) : src;
-  const res = new BidirIndex(null, { map, start: $src.nextID });
-  $src.pairs.forEach(([k, id]) => {
-    res.fwd.set(k, id);
-    res.rev.set(id, k);
-  });
-  return res;
-};
-export {
-  BidirIndex,
-  bidirIndexFromJSON,
-  defBidirIndex
-};
+export * from "./api.js";
+export * from "./bidir-index.js";
+export * from "./encode.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/bidir-index",
-  "version": "1.1.19",
+  "version": "1.2.0",
   "description": "Bi-directional index mapping arbitrary keys to numeric IDs & vice versa",
   "type": "module",
   "module": "./index.js",
@@ -39,13 +39,15 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "devDependencies": {
-    "esbuild": "^0.25.2",
-    "typedoc": "^0.28.2",
+    "esbuild": "^0.25.3",
+    "typedoc": "^0.28.3",
     "typescript": "^5.8.3"
   },
   "keywords": [
     "bidirectional",
     "datastructure",
+    "decode",
+    "encode",
     "identifier",
     "invert",
     "iterator",
@@ -70,6 +72,15 @@
   "exports": {
     ".": {
       "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./bidir-index": {
+      "default": "./bidir-index.js"
+    },
+    "./encode": {
+      "default": "./encode.js"
     }
   },
   "thi.ng": {
@@ -78,5 +89,5 @@
     ],
     "year": 2022
   },
-  "gitHead": "c464b6948f92cba90c2ea75b59203dad894fb450\n"
+  "gitHead": "4354686a6fb1f82c09ea48f92f87786191b231a0\n"
 }