Skip to content

Commit

Permalink
refactor(associative): restructure & split-up package (#486)
Browse files Browse the repository at this point in the history 
BREAKING CHANGE: restructure & split-up package, update readme

- remove obsolete source files
- update pkg exports
  • Loading branch information
@postspectacular
postspectacular committed Jul 20, 2024
1 parent 9587f66 commit 8e59a63
Show file tree
Hide file tree
Showing 32 changed files with 33 additions and 1,786 deletions.
87 changes: 11 additions & 76 deletions packages/associative/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,14 @@
[![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 189 standalone projects, maintained as part
> This is one of 192 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)
- [Why?](#why)
- [Comparison with ES6 native types](#comparison-with-es6-native-types)
- [Status](#status)
- [Installation](#installation)
Expand All @@ -31,15 +30,21 @@
- [Ranged queries](#ranged-queries)
- [SortedSet](#sortedset)
- [SparseSet8/16/32](#sparseset81632)
- [TrieMap](#triemap)
- [MultiTrie](#multitrie)
- [Authors](#authors)
- [License](#license)

## About

Alternative Map and Set implementations with customizable equality semantics & supporting operations, plain object utilities.

> [!IMPORTANT]
> In July 2024 this package was restructured & split-up to extract some
> features into smaller more focused packages:
>
> - [@thi.ng/bidir-index](https://thi.ng/bidir-index)
> - [@thi.ng/object-utils](https://thi.ng/object-utils)
> - [@thi.ng/trie](https://thi.ng/trie)
- Array based `ArraySet`, Linked List based `LLSet`,
[Skiplist](https://en.wikipedia.org/wiki/Skip_list) based `SortedMap` &
`SortedSet` and customizable `EquivMap` implement the full ES6 Map/Set APIs
Expand All @@ -52,22 +57,12 @@ Alternative Map and Set implementations with customizable equality semantics & s
(maps) and `disj()` (sets)
- configurable key equality & comparison (incl. default implementations)
- getters w/ optional "not-found" default value
- `fromObject()` converters (for maps only)
- `TrieMap` for string-based keys and `MultiTrie` for array-like keys and
multiple values per key
- `SparseSet` implementations for numeric values
- Polymorphic set operations (union, intersection, difference) - works with both
native and custom Sets and retains their types
- Natural & selective
[joins](https://en.wikipedia.org/wiki/Relational_algebra#Joins_and_join-like_operators)
(incl. key renaming, ported from Clojure)
- Key-value pair inversion for maps and vanilla objects
- i.e. swaps `K => V` to `V => K`
- Single or multi-property index generation for maps and objects
- Key selection, renaming, segmenting, splitting, transformations for maps and
objects

### Why?

Please see these packages for some example use cases:

Expand Down Expand Up @@ -203,7 +198,7 @@ For Node.js REPL:
const assoc = await import("@thi.ng/associative");
```

Package sizes (brotli'd, pre-treeshake): ESM: 6.98 KB
Package sizes (brotli'd, pre-treeshake): ESM: 4.78 KB

## Dependencies

Expand All @@ -215,6 +210,7 @@ Package sizes (brotli'd, pre-treeshake): ESM: 6.98 KB
- [@thi.ng/dcons](https://github.com/thi-ng/umbrella/tree/develop/packages/dcons)
- [@thi.ng/equiv](https://github.com/thi-ng/umbrella/tree/develop/packages/equiv)
- [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
- [@thi.ng/object-utils](https://github.com/thi-ng/umbrella/tree/develop/packages/object-utils)
- [@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)
- [tslib](https://www.typescriptlang.org/)
Expand Down Expand Up @@ -365,67 +361,6 @@ const b = defSparseSet(0x10000);
// SparseSet16 {}
```

### TrieMap

[Tries](https://en.wikipedia.org/wiki/Trie) (also called Prefix maps) are useful
data structures for search based use cases, auto-complete, text indexing etc.
and provide partial key matching (prefixes), suffix iteration for a common
prefix, longest matching prefix queries etc.

The implementations here too feature ES6 Map-like API, similar to other types in
this package, with some further trie-specific additions.

```ts
import { defTrieMap } from "@thi.ng/associative";

const trie = defTrieMap([
["hey", "en"],
["hello", "en"],
["hallo", "de"],
["hallo", "de-at"],
["hola", "es"],
["hold", "en"],
["hej", "se"],
]);

trie.knownPrefix("hole")
// "hol"

[...trie.suffixes("he")]
// [ "j", "llo", "y" ]

// w/ prefix included
[...trie.suffixes("he", true)]
// [ "hej", "hello", "hey" ]
```

### MultiTrie

The `MultiTrie` is similar to `TrieMap`, but supports array-like keys and
multiple values per key. Values are stored in sets whose implementation can be
configured via ctor options.

```ts
import { defMultiTrie } from "@thi.ng/associative";

// init w/ custom value set type (here only for illustration)
const t = defMultiTrie<string[], string>(null, { vals: () => new ArraySet() });

t.add("to be or not to be".split(" "), 1);
t.add("to be or not to be".split(" "), 2);
t.add("to be and to live".split(" "), 3);

t.get("to be or not to be".split(" "))
// Set(2) { 1, 2 }

t.knownPrefix(["to", "be", "not"]);
// [ "to", "be" ]

// auto-complete w/ custom separator between words
[...t.suffixes(["to", "be"], false, "/")]
// [ "and/to/live", "or/not/to/be" ]
```

## Authors

- [Karsten Schmidt](https://thi.ng)
Expand Down
49 changes: 1 addition & 48 deletions packages/associative/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
"@thi.ng/dcons": "^3.2.118",
"@thi.ng/equiv": "^2.1.62",
"@thi.ng/errors": "^2.5.12",
"@thi.ng/object-utils": "^1.0.0",
"@thi.ng/random": "^3.8.5",
"@thi.ng/transducers": "^9.0.10",
"tslib": "^2.6.3"
Expand Down Expand Up @@ -96,36 +97,21 @@
"./array-set": {
"default": "./array-set.js"
},
"./bidir-index": {
"default": "./bidir-index.js"
},
"./checks": {
"default": "./checks.js"
},
"./common-keys": {
"default": "./common-keys.js"
},
"./copy": {
"default": "./copy.js"
},
"./difference": {
"default": "./difference.js"
},
"./dissoc": {
"default": "./dissoc.js"
},
"./empty": {
"default": "./empty.js"
},
"./equiv-map": {
"default": "./equiv-map.js"
},
"./first": {
"default": "./first.js"
},
"./from-keys": {
"default": "./from-keys.js"
},
"./hash-map": {
"default": "./hash-map.js"
},
Expand All @@ -138,39 +124,12 @@
"./into": {
"default": "./into.js"
},
"./invert": {
"default": "./invert.js"
},
"./join": {
"default": "./join.js"
},
"./ll-set": {
"default": "./ll-set.js"
},
"./merge-apply": {
"default": "./merge-apply.js"
},
"./merge-deep": {
"default": "./merge-deep.js"
},
"./merge-with": {
"default": "./merge-with.js"
},
"./merge": {
"default": "./merge.js"
},
"./multi-trie": {
"default": "./multi-trie.js"
},
"./partition-keys": {
"default": "./partition-keys.js"
},
"./rename-keys": {
"default": "./rename-keys.js"
},
"./select-keys": {
"default": "./select-keys.js"
},
"./sorted-map": {
"default": "./sorted-map.js"
},
Expand All @@ -183,14 +142,8 @@
"./sparse-set": {
"default": "./sparse-set.js"
},
"./trie-map": {
"default": "./trie-map.js"
},
"./union": {
"default": "./union.js"
},
"./without-keys": {
"default": "./without-keys.js"
}
},
"thi.ng": {
Expand Down
Loading

0 comments on commit 8e59a63

Please sign in to comment.