@thi.ng/bidir-index 1.4.2 → 1.5.0

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 213 standalone projects, maintained as part
+> This is one of 214 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -67,7 +67,7 @@ For Node.js REPL:
 const bi = await import("@thi.ng/bidir-index");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 999 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 1.04 KB
 
 ## Dependencies
 

package/bidir-index.d.ts

@@ -106,10 +106,17 @@ export declare class BidirIndex<T> implements IClear, ICopy<BidirIndex<T>>, IEmp
      * false), throws error if any of the given keys is unknown/unindexed (use
      * {@link BidirIndex.add} or {@link BidirIndex.addAll} first).
      *
+     * @remarks
+     * Only used if `fail=false` (default): If `all=true`, any unknown values
+     * will be mapped to `null` values in the result array. Otherwise, the
+     * default behavior is for such unknown values to be skipped.
+     *
      * @param keys
      * @param fail
+     * @param all
      */
     getAll(keys: Iterable<T>, fail?: boolean): number[];
+    getAll(keys: Iterable<T>, fail: boolean, all: true): (number | null)[];
     /**
      * Similar to {@link BidirIndex.getAll}, but returns result as ES6 Set,
      * thereby removing any duplicates in `keys`.
@@ -119,15 +126,31 @@ export declare class BidirIndex<T> implements IClear, ICopy<BidirIndex<T>>, IEmp
      */
     getAllUnique(keys: Iterable<T>, fail?: boolean): Set<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
+     * Reverse op of {@link BidirIndex.getAll}. 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).
      *
+     * @remarks
+     * Only used if `fail=false` (default): If `all=true`, any unknown IDs will
+     * be mapped to `null` values in the result array. Otherwise, the default
+     * behavior is for such unknown values to be skipped.
+     *
      * @param ids
      * @param fail
+     * @param all
      */
     getAllIDs(ids: Iterable<number>, fail?: boolean): T[];
+    getAllIDs(ids: Iterable<number>, fail: boolean, all: true): (T | null)[];
+    /**
+     * Attempts to rename `currKey` into `newKey` without changing its ID
+     * mapping. Returns `ok` if successful, otherwise `missing` if `currKey` is
+     * unknown or `conflict` if `newKey` already exists.
+     *
+     * @param currKey
+     * @param newKey
+     */
+    renameKey(currKey: T, newKey: T): "missing" | "conflict" | "ok";
     /**
      * Returns a compact JSON serializable version of the index. Use
      * {@link bidirIndexFromJSON} to instantiate an index from such a JSON

package/bidir-index.js

@@ -164,16 +164,8 @@ class BidirIndex {
   deleteAllIDs(ids) {
     for (const 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);
+  getAll(keys, fail = false, all) {
+    return __iterate(this.fwd, keys, fail, all);
   }
   /**
    * Similar to {@link BidirIndex.getAll}, but returns result as ES6 Set,
@@ -185,17 +177,26 @@ class BidirIndex {
   getAllUnique(keys, fail = false) {
     return new Set(__iterate(this.fwd, keys, fail));
   }
+  getAllIDs(ids, fail = false, all) {
+    return __iterate(this.rev, ids, fail, all);
+  }
   /**
-   * 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).
+   * Attempts to rename `currKey` into `newKey` without changing its ID
+   * mapping. Returns `ok` if successful, otherwise `missing` if `currKey` is
+   * unknown or `conflict` if `newKey` already exists.
    *
-   * @param ids
-   * @param fail
+   * @param currKey
+   * @param newKey
    */
-  getAllIDs(ids, fail = false) {
-    return __iterate(this.rev, ids, fail);
+  renameKey(currKey, newKey) {
+    const id1 = this.fwd.get(currKey);
+    if (id1 == null) return "missing";
+    const id2 = this.fwd.get(newKey);
+    if (id2 != null) return "conflict";
+    this.fwd.delete(currKey);
+    this.fwd.set(newKey, id1);
+    this.rev.set(id1, newKey);
+    return "ok";
   }
   /**
    * Returns a compact JSON serializable version of the index. Use
@@ -218,18 +219,19 @@ const __delete = (fwd, rev, key) => {
   }
   return false;
 };
-const __iterate = (index, keys, fail) => {
+function __iterate(index, keys, fail, all) {
   const res = [];
   for (const k of keys) {
     const val = index.get(k);
     if (val === void 0) {
       if (fail) throw new Error(`unknwon key/ID: ${k}`);
+      if (all) res.push(null);
     } 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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@thi.ng/bidir-index",
-	"version": "1.4.2",
+	"version": "1.5.0",
 	"description": "Bi-directional index mapping arbitrary keys to numeric IDs & vice versa",
 	"type": "module",
 	"module": "./index.js",
@@ -8,7 +8,8 @@
 	"sideEffects": false,
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/thi-ng/umbrella.git"
+		"url": "git+https://github.com/thi-ng/umbrella.git",
+		"directory": "packages/bidir-index"
 	},
 	"homepage": "https://thi.ng/bidir-index",
 	"funding": [
@@ -39,12 +40,12 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.12",
-		"@thi.ng/checks": "^3.8.2"
+		"@thi.ng/api": "^8.12.14",
+		"@thi.ng/checks": "^3.8.4"
 	},
 	"devDependencies": {
-		"esbuild": "^0.27.0",
-		"typedoc": "^0.28.14",
+		"esbuild": "^0.27.2",
+		"typedoc": "^0.28.16",
 		"typescript": "^5.9.3"
 	},
 	"keywords": [
@@ -94,5 +95,5 @@
 		],
 		"year": 2022
 	},
-	"gitHead": "deb511294f7a120091b654af0ff7e8a399a465b3\n"
+	"gitHead": "4bd1b9d8ae52ba32b90a1b9a55d329c708ca7865\n"
 }