@thi.ng/sorted-map 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Change Log
+
+- **Last updated**: 2024-07-22T13:15:57Z
+- **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org/) for commit guidelines.
+
+**Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
+and/or version bumps of transitive dependencies.
+
+## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/sorted-map@1.1.0) (2024-07-22)
+
+#### 🚀 Features
+
+- import as new pkg ([#486](https://github.com/thi-ng/umbrella/issues/486)) ([02602e8](https://github.com/thi-ng/umbrella/commit/02602e8))

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,218 @@
+<!-- This file is generated - DO NOT EDIT! -->
+<!-- Please see: https://github.com/thi-ng/umbrella/blob/develop/CONTRIBUTING.md#changes-to-readme-files -->
+# ![@thi.ng/sorted-map](https://media.thi.ng/umbrella/banners-20230807/thing-sorted-map.svg?a2ee1fc6)
+
+[![npm version](https://img.shields.io/npm/v/@thi.ng/sorted-map.svg)](https://www.npmjs.com/package/@thi.ng/sorted-map)
+![npm downloads](https://img.shields.io/npm/dm/@thi.ng/sorted-map.svg)
+[![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 198 standalone projects, maintained as part
+> of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
+> and anti-framework.
+>
+> 🚀 Please help me to work full-time on these projects by [sponsoring me on
+> GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
+
+- [About](#about)
+  - [SortedMap](#sortedmap)
+    - [Ranged queries](#ranged-queries)
+  - [SortedSet](#sortedset)
+- [Status](#status)
+- [Related packages](#related-packages)
+- [Installation](#installation)
+- [Dependencies](#dependencies)
+- [API](#api)
+  - [Basic usage](#basic-usage)
+- [Authors](#authors)
+- [License](#license)
+
+## About
+
+Skiplist-based sorted map & set implementation.
+
+This package contains functionality which was previously part of and has been
+extracted from the [@thi.ng/associative](https://thi.ng/associative) package.
+
+[Skiplist](https://en.wikipedia.org/wiki/Skip_list) based `SortedMap` &
+`SortedSet` implementing the full ES6 Map/Set APIs and additional features:
+
+- range query iterators (via `entries()`, `keys()`, `values()`)
+- [`ICompare`](https://docs.thi.ng/umbrella/api/interfaces/ICompare.html),
+  [`ICopy`](https://docs.thi.ng/umbrella/api/interfaces/ICopy.html),
+  [`IEmpty`](https://docs.thi.ng/umbrella/api/interfaces/IEmpty.html) &
+  [`IEquiv`](https://docs.thi.ng/umbrella/api/interfaces/IEquiv.html)
+  implementations
+- multiple value additions / updates / deletions via `.into()`, `.dissoc()` or
+  `.disj()`
+- configurable key equality & comparison (incl. default implementations)
+- getters w/ optional "not-found" default value
+
+The native ES6 implementations use **object reference** identity to determine
+key containment, but often it's **more practical and useful to use equivalent
+value semantics** for this purpose, especially when keys are structured data
+(arrays / objects).
+
+**Note**: It's the user's responsibility to ensure the inserted keys are kept
+immutable (even if technically they're not).
+
+### SortedMap
+
+Alternative implementation of the ES6 Map API using a Skip list as
+backing store and support for configurable key equality and sorting
+semantics. Like with sets, uses @thi.ng/equiv & @thi.ng/compare by
+default.
+
+William Pugh's (creator of this data structure) description:
+
+> "Skip lists are probabilistic data structures that have the same
+asymptotic expected time bounds as balanced trees, are simpler, faster
+and use less space."
+
+Data structure description:
+
+- ftp://ftp.cs.umd.edu/pub/skipLists/skiplists.pdf
+- https://en.wikipedia.org/wiki/Skip_list
+
+#### Ranged queries
+
+```ts
+import { defSortedMap } from "@thi.ng/sorted-map";
+
+map = defSortedMap([
+    ["c", 3], ["a", 1], ["d", 4], ["b", 2]
+]);
+// SortedMap { 'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4 }
+
+// all entries
+[...map.entries()]
+// [ [ 'd', 4 ], [ 'c', 3 ], [ 'b', 2 ], [ 'a', 1 ] ]
+
+// range query w/ given start key
+// also works with `keys()` and `values()`
+[...map.entries("c")]
+// [ [ 'c', 3 ], [ 'd', 4 ] ]
+
+// unknown start keys are ok
+[...map.entries("cc")]
+// [ [ 'd', 4 ] ]
+
+// range query w/ given MAX key
+[...map.entries("c", true)]
+// [ [ 'a', 1 ], [ 'b', 2 ], [ 'c', 3 ] ]
+```
+
+### SortedSet
+
+Sorted set implementation with standard ES6 Set API, customizable value
+equality and comparison semantics and additional functionality:
+
+- range queries (via `entries`, `keys`, `values`)
+- multiple value addition/deletion via `into()` and `disj()`
+
+Furthermore, this class implements the `ICopy`, `IEmpty`, `ICompare` and
+`IEquiv` interfaces defined by `@thi.ng/api`. The latter two allow
+instances to be used as keys themselves in other data types defined in
+this (and other) package(s).
+
+This set uses a `SortedMap` as backing store.
+
+## Status
+
+**STABLE** - used in production
+
+[Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bsorted-map%5D+in%3Atitle)
+
+## Related packages
+
+- [@thi.ng/associative](https://github.com/thi-ng/umbrella/tree/develop/packages/associative) - ES Map/Set-compatible implementations with customizable equality semantics & supporting operations
+
+## Installation
+
+```bash
+yarn add @thi.ng/sorted-map
+```
+
+ESM import:
+
+```ts
+import * as sm from "@thi.ng/sorted-map";
+```
+
+Browser ESM import:
+
+```html
+<script type="module" src="https://esm.run/@thi.ng/sorted-map"></script>
+```
+
+[JSDelivr documentation](https://www.jsdelivr.com/)
+
+For Node.js REPL:
+
+```js
+const sm = await import("@thi.ng/sorted-map");
+```
+
+Package sizes (brotli'd, pre-treeshake): ESM: 1.71 KB
+
+## Dependencies
+
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/associative](https://github.com/thi-ng/umbrella/tree/develop/packages/associative)
+- [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
+- [@thi.ng/compare](https://github.com/thi-ng/umbrella/tree/develop/packages/compare)
+- [@thi.ng/random](https://github.com/thi-ng/umbrella/tree/develop/packages/random)
+- [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
+
+Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
+
+## API
+
+[Generated API docs](https://docs.thi.ng/umbrella/sorted-map/)
+
+### Basic usage
+
+```ts
+import { defSortedSet, defSortedMap } from "@thi.ng/sorted-map";
+
+// define keys w/ equal values
+const a = [1, 2];
+const b = [1, 2];
+
+const set = defSortedSet([a, [-1, 2], [-1, -2]]);
+// SortedSet { [ -1, -2 ], [ -1, 2 ], [ 1, 2 ] }
+
+// `b` was not added directly, but the set uses value equality
+set.has(b);
+// true
+
+const map = defSortedMap([[a, "foo"], [[-1, -2], "bar"]]);
+// SortedMap { [ -1, -2 ] => 'bar', [ 1, 2 ] => 'foo' }
+
+// `b` was not added directly, but the set uses value equality
+map.get(b);
+// "foo"
+
+// key lookup w/ default value
+map.get([3, 4], "n/a");
+// "n/a"
+```
+
+## Authors
+
+- [Karsten Schmidt](https://thi.ng)
+
+If this project contributes to an academic publication, please cite it as:
+
+```bibtex
+@misc{thing-sorted-map,
+  title = "@thi.ng/sorted-map",
+  author = "Karsten Schmidt",
+  note = "https://thi.ng/sorted-map",
+  year = 2018
+}
+```
+
+## License
+
+&copy; 2018 - 2024 Karsten Schmidt // Apache License 2.0

package/api.d.ts

@@ -0,0 +1,37 @@
+import type { Comparator } from "@thi.ng/api";
+import type { IRandom } from "@thi.ng/random";
+/**
+ * SortedMapOpts implementation config settings.
+ */
+export interface SortedMapOpts<K> {
+    /**
+     * Key comparison function. Must follow standard comparator contract and
+     * return:
+     * - negative if `a < b`
+     * - positive if `a > b`
+     * - `0` if `a == b`
+     *
+     * Note: The {@link SortedMap} implementation only uses `<` and `==` style
+     * comparisons.
+     *
+     * @defaultValue
+     * [`compare()`](https://docs.thi.ng/umbrella/compare/functions/compare.html)
+     */
+    compare: Comparator<K>;
+    /**
+     * Probability for a value to exist in any express lane of the
+     * underlying Skip List implementation.
+     *
+     * @defaultValue `1 / Math.E`
+     */
+    probability: number;
+    /**
+     * Random number generator for choosing new insertion levels. By default
+     * uses
+     * [`SYSTEM`](https://docs.thi.ng/umbrella/random/variables/SYSTEM.html)
+     * from thi.ng/random pkg.
+     */
+    rnd: IRandom;
+}
+export type SortedSetOpts<T> = SortedMapOpts<T>;
+//# sourceMappingURL=api.d.ts.map

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./api.js";
+export * from "./sorted-map.js";
+export * from "./sorted-set.js";
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,3 @@
+export * from "./api.js";
+export * from "./sorted-map.js";
+export * from "./sorted-set.js";

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@thi.ng/sorted-map",
+  "version": "1.1.0",
+  "description": "Skiplist-based sorted map & set implementation",
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thi-ng/umbrella.git"
+  },
+  "homepage": "https://thi.ng/sorted-map",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/postspectacular"
+    },
+    {
+      "type": "patreon",
+      "url": "https://patreon.com/thing_umbrella"
+    }
+  ],
+  "author": "Karsten Schmidt (https://thi.ng)",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn build:esbuild && yarn build:decl",
+    "build:decl": "tsc --declaration --emitDeclarationOnly",
+    "build:esbuild": "esbuild --format=esm --platform=neutral --target=es2022 --tsconfig=tsconfig.json --outdir=. src/**/*.ts",
+    "clean": "bun ../../tools/src/clean-package.ts",
+    "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
+    "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
+    "doc:readme": "bun ../../tools/src/module-stats.ts && bun ../../tools/src/readme.ts",
+    "pub": "yarn npm publish --access public",
+    "test": "bun test",
+    "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
+  },
+  "dependencies": {
+    "@thi.ng/api": "^8.11.7",
+    "@thi.ng/associative": "^7.0.0",
+    "@thi.ng/checks": "^3.6.9",
+    "@thi.ng/compare": "^2.3.10",
+    "@thi.ng/random": "^4.0.0",
+    "@thi.ng/transducers": "^9.0.11"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.47.0",
+    "esbuild": "^0.23.0",
+    "typedoc": "^0.26.3",
+    "typescript": "^5.5.3"
+  },
+  "keywords": [
+    "datastructure",
+    "equality",
+    "iterator",
+    "keys",
+    "map",
+    "query",
+    "set",
+    "skiplist",
+    "sort",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "browser": {
+    "process": false,
+    "setTimeout": false
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "./*.js",
+    "./*.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./sorted-map": {
+      "default": "./sorted-map.js"
+    },
+    "./sorted-set": {
+      "default": "./sorted-set.js"
+    }
+  },
+  "thi.ng": {
+    "related": [
+      "associative"
+    ],
+    "year": 2018
+  },
+  "gitHead": "324d6b7dbf31558329e9fb6452e29b2f7db9c61a\n"
+}

package/sorted-map.d.ts

@@ -0,0 +1,115 @@
+import type { Fn3, IObjectOf, Maybe, Pair } from "@thi.ng/api";
+import type { Reduced, ReductionFn } from "@thi.ng/transducers";
+import type { SortedMapOpts } from "./api.js";
+/** @internal */
+declare class Node<K, V> {
+    k?: K | undefined;
+    v?: V | undefined;
+    level: number;
+    next: Maybe<Node<K, V>>;
+    prev: Maybe<Node<K, V>>;
+    up: Maybe<Node<K, V>>;
+    down: Maybe<Node<K, V>>;
+    constructor(k?: K | undefined, v?: V | undefined, level?: number);
+}
+/**
+ * Sorted map implementation based on Skip List data structure. Supports any
+ * keys (other than `undefined`) which can be sorted via user-defined
+ * comparator, given as ctor option.
+ *
+ * @remarks
+ * v6.3.0 .set() & .delete() implementations rewritten, based on:
+ *
+ * - https://en.wikipedia.org/wiki/Skip_list
+ * - https://www.youtube.com/watch?v=kBwUoWpeH_Q (MIT courseware)
+ * - https://www.educba.com/skip-list-java/
+ */
+export declare class SortedMap<K, V> extends Map<K, V> {
+    constructor(pairs?: Iterable<Pair<K, V>> | null, opts?: Partial<SortedMapOpts<K>>);
+    get size(): number;
+    get [Symbol.species](): typeof SortedMap;
+    [Symbol.iterator](): IterableIterator<Pair<K, V>>;
+    /**
+     * Yields iterator of sorted `[key, value]` pairs, optionally taking given
+     * `key` and `max` flag into account.
+     *
+     * @remarks
+     * If `key` is given and `max=false`, the key is used as minimum search key
+     * and the iterator will only yield pairs for which keys are `>=` given key.
+     * If `max=true`, the given is used as maximum and only yields pairs for
+     * which keys are `<=` given key.
+     *
+     * If **no** key is given, yields **all** pairs.
+     *
+     * @param key
+     * @param max
+     */
+    entries(key?: K, max?: boolean): IterableIterator<Pair<K, V>>;
+    /**
+     * Similar to {@link SortedMap.entries}, but only yield sequence of keys.
+     *
+     * @param key
+     * @param max
+     */
+    keys(key?: K, max?: boolean): IterableIterator<K>;
+    /**
+     * Similar to {@link SortedMap.entries}, but only yield sequence of values.
+     *
+     * @param key
+     * @param max
+     */
+    values(key?: K, max?: boolean): IterableIterator<V>;
+    clear(): void;
+    empty(): SortedMap<K, V>;
+    copy(): SortedMap<K, V>;
+    compare(o: Map<K, V>): number;
+    equiv(o: any): boolean;
+    first(): (V | (K & ({} | null)) | undefined)[] | undefined;
+    get(key: K, notFound?: V): Maybe<V>;
+    has(key: K): boolean;
+    set(key: K, val: V): this;
+    delete(key: K): boolean;
+    into(pairs: Iterable<Pair<K, V>>): this;
+    dissoc(keys: Iterable<K>): this;
+    /**
+     * The key & value args given the callback `fn` MUST be treated as
+     * readonly/immutable. This could be enforced via TS, but would
+     * break ES6 Map interface contract.
+     *
+     * @param fn -
+     * @param thisArg -
+     */
+    forEach(fn: Fn3<V, K, Map<K, V>, void>, thisArg?: any): void;
+    $reduce<R>(rfn: ReductionFn<Pair<K, V>, R>, acc: R | Reduced<R>): R | Reduced<R>;
+    opts(): SortedMapOpts<K>;
+    /**
+     * Inserts `b` as successor of `a` (in the same lane as `a`).
+     *
+     * @param a
+     * @param b
+     */
+    protected insertInLane(a: Node<K, V>, b: Node<K, V>): void;
+    /**
+     * Links lanes by connecting `a` and `b` vertically.
+     *
+     * @param a
+     * @param b
+     */
+    protected linkLanes(a: Node<K, V>, b: Node<K, V>): void;
+    /**
+     * Returns first node on lowest level. Unless the map is empty, this node
+     * will be the first data node (with the smallest key).
+     */
+    protected firstNode(): Node<K, V>;
+    /**
+     * Returns the first matching (or predecessor) node for given key (NOT
+     * necessarily at the lowest level).
+     *
+     * @param key
+     */
+    protected findNode(key: K): Node<K, V>;
+}
+export declare function defSortedMap<K, V>(pairs?: Iterable<Pair<K, V>> | null, opts?: Partial<SortedMapOpts<K>>): SortedMap<K, V>;
+export declare function defSortedMap<V>(obj: IObjectOf<V>, opts?: Partial<SortedMapOpts<string>>): SortedMap<string, V>;
+export {};
+//# sourceMappingURL=sorted-map.d.ts.map

package/sorted-map.js

@@ -0,0 +1,324 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+import { dissoc } from "@thi.ng/associative/dissoc";
+import { __equivMap } from "@thi.ng/associative/internal/equiv";
+import { __inspectable } from "@thi.ng/associative/internal/inspect";
+import { into } from "@thi.ng/associative/into";
+import { isPlainObject } from "@thi.ng/checks/is-plain-object";
+import { compare } from "@thi.ng/compare/compare";
+import { SYSTEM } from "@thi.ng/random/system";
+import { map } from "@thi.ng/transducers/map";
+import { isReduced } from "@thi.ng/transducers/reduced";
+class Node {
+  constructor(k, v, level = 0) {
+    this.k = k;
+    this.v = v;
+    this.level = level;
+  }
+  next;
+  prev;
+  up;
+  down;
+}
+const __private = /* @__PURE__ */ new WeakMap();
+let SortedMap = class extends Map {
+  constructor(pairs, opts = {}) {
+    super();
+    __private.set(this, {
+      head: new Node(),
+      cmp: opts.compare || compare,
+      rnd: opts.rnd || SYSTEM,
+      p: opts.probability || 1 / Math.E,
+      size: 0
+    });
+    if (pairs) {
+      this.into(pairs);
+    }
+  }
+  get size() {
+    return __private.get(this).size;
+  }
+  get [Symbol.species]() {
+    return SortedMap;
+  }
+  *[Symbol.iterator]() {
+    let node = this.firstNode();
+    while (node && node.k !== void 0) {
+      yield [node.k, node.v];
+      node = node.next;
+    }
+  }
+  /**
+   * Yields iterator of sorted `[key, value]` pairs, optionally taking given
+   * `key` and `max` flag into account.
+   *
+   * @remarks
+   * If `key` is given and `max=false`, the key is used as minimum search key
+   * and the iterator will only yield pairs for which keys are `>=` given key.
+   * If `max=true`, the given is used as maximum and only yields pairs for
+   * which keys are `<=` given key.
+   *
+   * If **no** key is given, yields **all** pairs.
+   *
+   * @param key
+   * @param max
+   */
+  *entries(key, max = false) {
+    if (key === void 0) {
+      yield* this;
+      return;
+    }
+    const { cmp, size } = __private.get(this);
+    if (!size) return;
+    if (max) {
+      let node = this.firstNode();
+      while (node && node.k !== void 0 && cmp(node.k, key) <= 0) {
+        yield [node.k, node.v];
+        node = node.next;
+      }
+    } else {
+      let node = this.firstNode();
+      while (node.down) node = node.down;
+      while (node) {
+        if (node.k !== void 0 && cmp(node.k, key) >= 0) {
+          yield [node.k, node.v];
+        }
+        node = node.next;
+      }
+    }
+  }
+  /**
+   * Similar to {@link SortedMap.entries}, but only yield sequence of keys.
+   *
+   * @param key
+   * @param max
+   */
+  keys(key, max = false) {
+    return map((p) => p[0], this.entries(key, max));
+  }
+  /**
+   * Similar to {@link SortedMap.entries}, but only yield sequence of values.
+   *
+   * @param key
+   * @param max
+   */
+  values(key, max = false) {
+    return map((p) => p[1], this.entries(key, max));
+  }
+  clear() {
+    const $this = __private.get(this);
+    $this.head = new Node();
+    $this.size = 0;
+  }
+  empty() {
+    return new SortedMap(null, this.opts());
+  }
+  copy() {
+    return new SortedMap(this, this.opts());
+  }
+  compare(o) {
+    const n = this.size;
+    const m = o.size;
+    if (n < m) return -1;
+    if (n > m) return 1;
+    const i = this.entries();
+    const j = o.entries();
+    let x, y;
+    let c;
+    while (x = i.next(), y = j.next(), !x.done && !y.done) {
+      if ((c = compare(x.value[0], y.value[0])) !== 0 || (c = compare(x.value[1], y.value[1])) !== 0) {
+        return c;
+      }
+    }
+    return 0;
+  }
+  equiv(o) {
+    return __equivMap(this, o);
+  }
+  first() {
+    const node = this.firstNode();
+    return node && node.k !== void 0 ? [node.k, node.v] : void 0;
+  }
+  get(key, notFound) {
+    const $this = __private.get(this);
+    const node = this.findNode(key);
+    return node.k !== void 0 && $this.cmp(node.k, key) === 0 ? node.v : notFound;
+  }
+  has(key) {
+    const { cmp } = __private.get(this);
+    const node = this.findNode(key);
+    return node.k !== void 0 && cmp(node.k, key) === 0;
+  }
+  set(key, val) {
+    const $this = __private.get(this);
+    const { cmp, p, rnd } = $this;
+    let node = this.findNode(key);
+    if (node.k !== void 0 && cmp(node.k, key) === 0) {
+      node.v = val;
+      while (node.down) {
+        node = node.down;
+        node.v = val;
+      }
+      return this;
+    }
+    let newNode = new Node(key, val, node.level);
+    this.insertInLane(node, newNode);
+    let currLevel = node.level;
+    let headLevel = $this.head.level;
+    while (rnd.probability(p)) {
+      if (currLevel >= headLevel) {
+        const newHead = new Node(
+          void 0,
+          void 0,
+          headLevel + 1
+        );
+        this.linkLanes(newHead, $this.head);
+        $this.head = newHead;
+        headLevel++;
+      }
+      while (!node.up) node = node.prev;
+      node = node.up;
+      const tmp = new Node(key, val, node.level);
+      this.insertInLane(node, tmp);
+      this.linkLanes(tmp, newNode);
+      newNode = tmp;
+      currLevel++;
+    }
+    $this.size++;
+    return this;
+  }
+  delete(key) {
+    const $this = __private.get(this);
+    let node = this.findNode(key);
+    if (node.k === void 0 || $this.cmp(node.k, key) !== 0) return false;
+    while (node.down) node = node.down;
+    let prev;
+    let next;
+    while (node) {
+      prev = node.prev;
+      next = node.next;
+      if (prev) prev.next = next;
+      if (next) next.prev = prev;
+      node = node.up;
+    }
+    while (!$this.head.next && $this.head.down) {
+      $this.head = $this.head.down;
+      $this.head.up = void 0;
+    }
+    $this.size--;
+    return true;
+  }
+  into(pairs) {
+    return into(this, pairs);
+  }
+  dissoc(keys) {
+    return dissoc(this, keys);
+  }
+  /**
+   * The key & value args given the callback `fn` MUST be treated as
+   * readonly/immutable. This could be enforced via TS, but would
+   * break ES6 Map interface contract.
+   *
+   * @param fn -
+   * @param thisArg -
+   */
+  forEach(fn, thisArg) {
+    for (let p of this) {
+      fn.call(thisArg, p[1], p[0], this);
+    }
+  }
+  $reduce(rfn, acc) {
+    let node = this.firstNode();
+    while (node && node.k !== void 0 && !isReduced(acc)) {
+      acc = rfn(acc, [node.k, node.v]);
+      node = node.next;
+    }
+    return acc;
+  }
+  opts() {
+    const $this = __private.get(this);
+    return {
+      compare: $this.cmp,
+      probability: $this.p,
+      rnd: $this.rnd
+    };
+  }
+  /**
+   * Inserts `b` as successor of `a` (in the same lane as `a`).
+   *
+   * @param a
+   * @param b
+   */
+  insertInLane(a, b) {
+    b.prev = a;
+    b.next = a.next;
+    if (a.next) a.next.prev = b;
+    a.next = b;
+  }
+  /**
+   * Links lanes by connecting `a` and `b` vertically.
+   *
+   * @param a
+   * @param b
+   */
+  linkLanes(a, b) {
+    a.down = b;
+    b.up = a;
+  }
+  /**
+   * Returns first node on lowest level. Unless the map is empty, this node
+   * will be the first data node (with the smallest key).
+   */
+  firstNode() {
+    const { head } = __private.get(this);
+    let node = head;
+    while (node.down) node = node.down;
+    while (node.prev) node = node.prev;
+    if (node.next) node = node.next;
+    return node;
+  }
+  /**
+   * Returns the first matching (or predecessor) node for given key (NOT
+   * necessarily at the lowest level).
+   *
+   * @param key
+   */
+  findNode(key) {
+    let { cmp, head } = __private.get(this);
+    let node = head;
+    let next;
+    let down;
+    let nodeKey;
+    while (true) {
+      next = node.next;
+      while (next && cmp(next.k, key) <= 0) {
+        node = next;
+        next = node.next;
+      }
+      nodeKey = node.k;
+      if (nodeKey !== void 0 && cmp(nodeKey, key) === 0) break;
+      down = node.down;
+      if (!down) break;
+      node = down;
+    }
+    return node;
+  }
+};
+SortedMap = __decorateClass([
+  __inspectable
+], SortedMap);
+function defSortedMap(src, opts) {
+  return isPlainObject(src) ? new SortedMap(Object.entries(src), opts) : new SortedMap(src, opts);
+}
+export {
+  SortedMap,
+  defSortedMap
+};

package/sorted-set.d.ts

@@ -0,0 +1,59 @@
+import type { Fn3, ICompare, Maybe, Pair } from "@thi.ng/api";
+import type { IEquivSet } from "@thi.ng/associative";
+import type { IReducible, Reduced, ReductionFn } from "@thi.ng/transducers";
+import type { SortedSetOpts } from "./api.js";
+/**
+ * Sorted set implementation with standard ES6 Set API, customizable value
+ * equality and comparison semantics and additional functionality:
+ *
+ * - range queries (via {@link SortedSet.entries}, {@link SortedSet.keys},
+ *   {@link SortedSet.values})
+ * - multiple value addition/deletion via {@link SortedSet.into} and
+ *   {@link SortedSet.disj}
+ *
+ * Furthermore, this class implements the
+ * [`ICopy`](https://docs.thi.ng/umbrella/api/interfaces/ICopy.html), IEmpty`,
+ * [`ICompare`](https://docs.thi.ng/umbrella/api/interfaces/ICompare.html) and
+ * [`IEquiv`](https://docs.thi.ng/umbrella/api/interfaces/IEquiv.html)
+ * interfaces defined by [`thi.ng/api`](https://thi.ng/api). The latter two
+ * allow instances to be used as keys themselves in other data types defined in
+ * this (and other) package(s).
+ *
+ * This set uses a {@link SortedMap} as backing store and therefore has the same
+ * resizing characteristics.
+ */
+export declare class SortedSet<T> extends Set<T> implements IEquivSet<T>, ICompare<Set<T>>, IReducible<T, any> {
+    /**
+     * Creates new instance with optional given values and/or
+     * implementation options. The options are the same as used by
+     * {@link SortedMap}.
+     *
+     * @param values - input values
+     * @param opts - config options
+     */
+    constructor(values?: Iterable<T> | null, opts?: Partial<SortedSetOpts<T>>);
+    [Symbol.iterator](): IterableIterator<T>;
+    get [Symbol.species](): typeof SortedSet;
+    get [Symbol.toStringTag](): string;
+    get size(): number;
+    copy(): SortedSet<T>;
+    empty(): SortedSet<T>;
+    compare(o: Set<T>): number;
+    equiv(o: any): boolean;
+    $reduce<R>(rfn: ReductionFn<T, any>, acc: R | Reduced<R>): R | Reduced<R>;
+    entries(key?: T, max?: boolean): IterableIterator<Pair<T, T>>;
+    keys(key?: T, max?: boolean): IterableIterator<T>;
+    values(key?: T, max?: boolean): IterableIterator<T>;
+    add(key: T): this;
+    into(keys: Iterable<T>): this;
+    clear(): void;
+    first(): T;
+    delete(key: T): boolean;
+    disj(keys: Iterable<T>): this;
+    forEach(fn: Fn3<Readonly<T>, Readonly<T>, Set<T>, void>, thisArg?: any): void;
+    has(key: T): boolean;
+    get(key: T, notFound?: T): Maybe<T>;
+    opts(): SortedSetOpts<T>;
+}
+export declare const defSortedSet: <T>(vals?: Iterable<T> | null, opts?: Partial<SortedSetOpts<T>>) => SortedSet<T>;
+//# sourceMappingURL=sorted-set.d.ts.map

package/sorted-set.js

@@ -0,0 +1,129 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+import { dissoc } from "@thi.ng/associative/dissoc";
+import { __equivSet } from "@thi.ng/associative/internal/equiv";
+import { __inspectable } from "@thi.ng/associative/internal/inspect";
+import { into } from "@thi.ng/associative/into";
+import { compare } from "@thi.ng/compare/compare";
+import { map } from "@thi.ng/transducers/map";
+import { SortedMap } from "./sorted-map.js";
+const __private = /* @__PURE__ */ new WeakMap();
+let SortedSet = class extends Set {
+  /**
+   * Creates new instance with optional given values and/or
+   * implementation options. The options are the same as used by
+   * {@link SortedMap}.
+   *
+   * @param values - input values
+   * @param opts - config options
+   */
+  constructor(values, opts) {
+    super();
+    __private.set(
+      this,
+      new SortedMap(
+        values ? map((x) => [x, x], values) : null,
+        opts
+      )
+    );
+  }
+  [Symbol.iterator]() {
+    return this.keys();
+  }
+  get [Symbol.species]() {
+    return SortedSet;
+  }
+  get [Symbol.toStringTag]() {
+    return "SortedSet";
+  }
+  get size() {
+    return __private.get(this).size;
+  }
+  copy() {
+    return new SortedSet(this.keys(), this.opts());
+  }
+  empty() {
+    return new SortedSet(null, this.opts());
+  }
+  compare(o) {
+    const n = this.size;
+    const m = o.size;
+    if (n < m) return -1;
+    if (n > m) return 1;
+    const i = this.entries();
+    const j = o.entries();
+    let x, y;
+    let c;
+    while (x = i.next(), y = j.next(), !x.done && !y.done) {
+      if ((c = compare(x.value[0], y.value[0])) !== 0) {
+        return c;
+      }
+    }
+    return 0;
+  }
+  equiv(o) {
+    return __equivSet(this, o);
+  }
+  $reduce(rfn, acc) {
+    return __private.get(this).$reduce((_acc, x) => rfn(_acc, x[0]), acc);
+  }
+  entries(key, max = false) {
+    return __private.get(this).entries(key, max);
+  }
+  keys(key, max = false) {
+    return __private.get(this).keys(key, max);
+  }
+  values(key, max = false) {
+    return __private.get(this).values(key, max);
+  }
+  add(key) {
+    __private.get(this).set(key, key);
+    return this;
+  }
+  into(keys) {
+    return into(this, keys);
+  }
+  clear() {
+    __private.get(this).clear();
+  }
+  first() {
+    const first = __private.get(this).first();
+    return first ? first[0] : void 0;
+  }
+  delete(key) {
+    return __private.get(this).delete(key);
+  }
+  disj(keys) {
+    return dissoc(this, keys);
+  }
+  forEach(fn, thisArg) {
+    for (let p of this) {
+      fn.call(thisArg, p, p, this);
+    }
+  }
+  has(key) {
+    return __private.get(this).has(key);
+  }
+  get(key, notFound) {
+    return __private.get(this).get(key, notFound);
+  }
+  opts() {
+    return __private.get(this).opts();
+  }
+};
+SortedSet = __decorateClass([
+  __inspectable
+], SortedSet);
+const defSortedSet = (vals, opts) => new SortedSet(vals, opts);
+export {
+  SortedSet,
+  defSortedSet
+};