Skip to content

Commit d7a9027

Browse files
vitokevitoke
authored
Merge pull request #63 from rimbu-org/feature/improve-docs
Feature/improve docs
2 parents 394df7a + 71482a3 commit d7a9027

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

83 files changed

+1170
-711
lines changed

‎README.md

+22-11
Original file line numberDiff line numberDiff line change
@@ -17,27 +17,38 @@ Rimbu is a TypeScript library focused on _immutable, performant, and type-safe c
1717
- Provides sane defaults but allows extensive customization and configuration.
1818
- A novel and efficient immutable random-access List implementation.
1919

20-
For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_.
20+
For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_ or the _[Rimbu API Docs](https://rimbu.org/api)_.
2121

2222
Or [Try Out Rimbu](https://codesandbox.io/s/github/vitoke/rimbu-sandbox/tree/main?previewwindow=console&view=split&editorsize=65&moduleview=1&module=/src/index.ts) in CodeSandBox.
2323

2424
## Main exports
2525

26-
The main exported projects are:
27-
28-
| Name | Description |
29-
| ---------------------------------- | ----------------------------------------------------------------------------------------------------- |
30-
| [@rimbu/core](packages/core) | Immutable collections including `List`, `SortedMap`, `EdgeGraph`, `HashBiMultiMap` and many more. |
31-
| [@rimbu/actor](packages/actor) | A framework-agnostic synchronous state management library that uses immutable objects under the hood. |
32-
| [@rimbu/reactor](packages/reactor) | A framework that allows usage of `@rimbu/actor` objects in `React`. |
33-
34-
## Getting started with this monorepo
26+
The main exported packages are:
27+
28+
| Name | Description |
29+
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
30+
| [@rimbu/bimap](packages/bimap) | a bidirectional map in which keys and values have a one-to-one mapping |
31+
| [@rimbu/bimultimap](packages/bimultimap) | a bidirectional multimap in which keys and values have a many-to-many mapping |
32+
| [@rimbu/collection-types](packages/collection-types) | definitions for many of the generic collection types, used to derive more specific implementations |
33+
| [@rimbu/common](packages/common) | contains public types and functions that are used throughout the whole library |
34+
| [@rimbu/core](packages/core) | a convenience package that exports most of the main types from the other packages |
35+
| [@rimbu/deep](packages/deep) | offers tools to use handle plain JS objects as immutable objects. library |
36+
| [@rimbu/graph](packages/graph) | provides various graph implementations to represent data in forms of nodes and edges |
37+
| [@rimbu/hashed](packages/hashed) | provides a HashMap and HashSet implementation, using hash functions to efficiently retrieve keys |
38+
| [@rimbu/list](packages/list) | provides the List datastructure containing an ordered sequence of elements that can be manipulated and accessed randomly in an efficient way |
39+
| [@rimbu/multimap](packages/multimap) | provides a map in which keys and values have a one-to-many mapping |
40+
| [@rimbu/multiset](packages/multiset) | provides a set in which elements can occur multiple times |
41+
| [@rimbu/ordered](packages/ordered) | provides the OrderedSet and OrderedMap collections, that keep insertion order |
42+
| [@rimbu/sorted](packages/sorted) | provides a SortedMap and SortedSet implementation, using compare functions to efficiently keep the elements sorted |
43+
| [@rimbu/stream](packages/stream) | contains methods to easily manipulate sequences of data |
44+
| [@rimbu/table](packages/table) | provides various Table data structures where a combination of a row key and column key maps to a single |
45+
46+
## Development: Getting started with this monorepo
3547

3648
1. Clone this repository
3749
2. Run `yarn setup`
3850

3951
To build all the packages: `yarn build`
40-
To start the Rimbu Docs locally: `yarn docsify`
4152
To run the tests: `yarn test`
4253

4354
## Author

‎deno_dist/README.md

+22-11
Original file line numberDiff line numberDiff line change
@@ -17,27 +17,38 @@ Rimbu is a TypeScript library focused on _immutable, performant, and type-safe c
1717
- Provides sane defaults but allows extensive customization and configuration.
1818
- A novel and efficient immutable random-access List implementation.
1919

20-
For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_.
20+
For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_ or the _[Rimbu API Docs](https://rimbu.org/api)_.
2121

2222
Or [Try Out Rimbu](https://codesandbox.io/s/github/vitoke/rimbu-sandbox/tree/main?previewwindow=console&view=split&editorsize=65&moduleview=1&module=/src/index.ts) in CodeSandBox.
2323

2424
## Main exports
2525

26-
The main exported projects are:
27-
28-
| Name | Description |
29-
| ---------------------------------- | ----------------------------------------------------------------------------------------------------- |
30-
| [@rimbu/core](packages/core) | Immutable collections including `List`, `SortedMap`, `EdgeGraph`, `HashBiMultiMap` and many more. |
31-
| [@rimbu/actor](packages/actor) | A framework-agnostic synchronous state management library that uses immutable objects under the hood. |
32-
| [@rimbu/reactor](packages/reactor) | A framework that allows usage of `@rimbu/actor` objects in `React`. |
33-
34-
## Getting started with this monorepo
26+
The main exported packages are:
27+
28+
| Name | Description |
29+
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
30+
| [@rimbu/bimap](packages/bimap) | a bidirectional map in which keys and values have a one-to-one mapping |
31+
| [@rimbu/bimultimap](packages/bimultimap) | a bidirectional multimap in which keys and values have a many-to-many mapping |
32+
| [@rimbu/collection-types](packages/collection-types) | definitions for many of the generic collection types, used to derive more specific implementations |
33+
| [@rimbu/common](packages/common) | contains public types and functions that are used throughout the whole library |
34+
| [@rimbu/core](packages/core) | a convenience package that exports most of the main types from the other packages |
35+
| [@rimbu/deep](packages/deep) | offers tools to use handle plain JS objects as immutable objects. library |
36+
| [@rimbu/graph](packages/graph) | provides various graph implementations to represent data in forms of nodes and edges |
37+
| [@rimbu/hashed](packages/hashed) | provides a HashMap and HashSet implementation, using hash functions to efficiently retrieve keys |
38+
| [@rimbu/list](packages/list) | provides the List datastructure containing an ordered sequence of elements that can be manipulated and accessed randomly in an efficient way |
39+
| [@rimbu/multimap](packages/multimap) | provides a map in which keys and values have a one-to-many mapping |
40+
| [@rimbu/multiset](packages/multiset) | provides a set in which elements can occur multiple times |
41+
| [@rimbu/ordered](packages/ordered) | provides the OrderedSet and OrderedMap collections, that keep insertion order |
42+
| [@rimbu/sorted](packages/sorted) | provides a SortedMap and SortedSet implementation, using compare functions to efficiently keep the elements sorted |
43+
| [@rimbu/stream](packages/stream) | contains methods to easily manipulate sequences of data |
44+
| [@rimbu/table](packages/table) | provides various Table data structures where a combination of a row key and column key maps to a single |
45+
46+
## Development: Getting started with this monorepo
3547

3648
1. Clone this repository
3749
2. Run `yarn setup`
3850

3951
To build all the packages: `yarn build`
40-
To start the Rimbu Docs locally: `yarn docsify`
4152
To run the tests: `yarn test`
4253

4354
## Author

‎deno_dist/actor/README.md

+28-15
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66

77
This package offers state management tools to create stateful logic that can be easily integrated in any framework.
88

9-
For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_.
9+
This package is still experimental, and therefore does not yet have complete documentation.
10+
11+
For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_ or the _[Rimbu API Docs](https://rimbu.org/api)_.
1012

1113
## Installation
1214

@@ -20,29 +22,40 @@ or
2022
2123
### Deno
2224

23-
Create a file called `rimbu.ts` and add the following:
25+
For Deno, the following approach is recommended:
26+
27+
In the root folder of your project, create or edit a file called `import_map.json` with the following contents (where you should replace `x.y.z` with the desired version of Rimbu):
28+
29+
```json
30+
{
31+
"imports": {
32+
"@rimbu/": "https://deno.land/x/rimbu@x.y.z/"
33+
}
34+
}
35+
```
2436

25-
> ```ts
26-
> export * from 'https://deno.land/x/rimbu/actor/mod.ts';
27-
> ```
37+
**Note: The trailing slashes are important!**
2838

29-
Or using a pinned version (`x.y.z`):
39+
In this way you can use relative imports from Rimbu in your code, like so:
3040

31-
> ```ts
32-
> export * from 'https://deno.land/x/rimbu/actor@x.y.z/mod.ts';
33-
> ```
41+
```ts
42+
import { List } from '@rimbu/core/mod.ts';
43+
import { HashMap } from '@rimbu/hashed/mod.ts';
44+
```
3445

35-
Then import what you need from `rimbu.ts`:
46+
Note that for sub-packages, due to conversion limitations it is needed to import the `index.ts` instead of `mod.ts`, like so:
3647

3748
```ts
38-
import { Actor } from './rimbu.ts';
49+
import { HashMap } from '@rimbu/hashed/map/index.ts';
3950
```
4051

41-
Because Rimbu uses complex types, it's recommended to use the `--no-check` flag (your editor should already have checked your code) and to specify a `tsconfig.json` file with the settings described below.
52+
To run your script (let's assume the entry point is in `src/main.ts`):
53+
54+
`deno run --import-map import_map.json src/main.ts`
4255

43-
Running your script then becomes:
56+
Because Rimbu uses advanced types, this may slow down the type checking part when running your code. If you're able to rely on your code editor to provide type errors, you can skip the Deno type check using the `--no-check` flag:
4457

45-
> `deno run --no-check --config tsconfig.json <your-script>.ts`
58+
`deno run --import-map import_map.json --no-check src/main.ts`
4659

4760
## Usage
4861

@@ -79,7 +92,7 @@ Feel very welcome to contribute to further improve Rimbu. Please read our [Contr
7992

8093
## Contributors
8194

82-
<img src = "https://contrib.rocks/image?repo=vitoke/iternal"/>
95+
<img src = "https://contrib.rocks/image?repo=rimbu-org/rimbu"/>
8396

8497
Made with [contributors-img](https://contrib.rocks).
8598

‎deno_dist/base/README.md

+26-15
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This package contains mostly utilities to implement the other Rimbu collections.
88

99
Most important are the exported `Arr` methods that are used at the basis of all the block-based data structures. These methods should be as correct and efficient as possible.
1010

11-
For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_.
11+
For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_ or the _[Rimbu API Docs](https://rimbu.org/api)_
1212

1313
## Installation
1414

@@ -22,29 +22,40 @@ or
2222
2323
### Deno
2424

25-
Create a file called `rimbu.ts` and add the following:
25+
For Deno, the following approach is recommended:
2626

27-
> ```ts
28-
> export * from 'https://deno.land/x/rimbu/base/mod.ts';
29-
> ```
27+
In the root folder of your project, create or edit a file called `import_map.json` with the following contents (where you should replace `x.y.z` with the desired version of Rimbu):
3028

31-
Or using a pinned version (`x.y.z`):
29+
```json
30+
{
31+
"imports": {
32+
"@rimbu/": "https://deno.land/x/rimbu@x.y.z/"
33+
}
34+
}
35+
```
36+
37+
**Note: The trailing slashes are important!**
38+
39+
In this way you can use relative imports from Rimbu in your code, like so:
3240

33-
> ```ts
34-
> export * from 'https://deno.land/x/rimbu/base@x.y.z/mod.ts';
35-
> ```
41+
```ts
42+
import { List } from '@rimbu/core/mod.ts';
43+
import { HashMap } from '@rimbu/hashed/mod.ts';
44+
```
3645

37-
Then import what you need from `rimbu.ts`:
46+
Note that for sub-packages, due to conversion limitations it is needed to import the `index.ts` instead of `mod.ts`, like so:
3847

3948
```ts
40-
import { Arr } from './rimbu.ts';
49+
import { HashMap } from '@rimbu/hashed/map/index.ts';
4150
```
4251

43-
Because Rimbu uses complex types, it's recommended to use the `--no-check` flag (your editor should already have checked your code) and to specify a `tsconfig.json` file with the settings described below.
52+
To run your script (let's assume the entry point is in `src/main.ts`):
53+
54+
`deno run --import-map import_map.json src/main.ts`
4455

45-
Running your script then becomes:
56+
Because Rimbu uses advanced types, this may slow down the type checking part when running your code. If you're able to rely on your code editor to provide type errors, you can skip the Deno type check using the `--no-check` flag:
4657

47-
> `deno run --no-check --config tsconfig.json <your-script>.ts`
58+
`deno run --import-map import_map.json --no-check src/main.ts`
4859

4960
## Usage
5061

@@ -69,7 +80,7 @@ Feel very welcome to contribute to further improve Rimbu. Please read our [Contr
6980

7081
## Contributors
7182

72-
<img src = "https://contrib.rocks/image?repo=vitoke/iternal"/>
83+
<img src = "https://contrib.rocks/image?repo=rimbu-org/rimbu"/>
7384

7485
Made with [contributors-img](https://contrib.rocks).
7586

‎deno_dist/bimap/README.md

+27-16
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@ This package exports the following types:
1414
| `HashBiMap<K, V>` | a BiMap between keys of type K and values of type V, where both the keys and values are hashed |
1515
| `SortedBiMap<K, V>` | a BiMap between keys of type K and values of type V, where both the keys and values are sorted |
1616

17-
For complete documentation please visit the [BiMap page](https://rimbu.org/docs/collections/bimap) in the _[Rimbu Docs](https://rimbu.org)_.
17+
For complete documentation please visit the [BiMap page](https://rimbu.org/docs/collections/bimap) in the _[Rimbu Docs](https://rimbu.org)_, or directly see the _[Rimbu BiMap API Docs](https://rimbu.org/api/rimbu/bimap)_.
1818

1919
Or [Try Out Rimbu](https://codesandbox.io/s/github/vitoke/rimbu-sandbox/tree/main?previewwindow=console&view=split&editorsize=65&moduleview=1&module=/src/index.ts) in CodeSandBox.
2020

2121
## Installation
2222

23-
All types are exported through [`@rimbu/core`](../core). It is recommended to use that package.
23+
For convenience, all main types are also exported through [`@rimbu/core`](../core).
2424

2525
To install this package only:
2626

@@ -34,29 +34,40 @@ or
3434
3535
### Deno
3636

37-
Create a file called `rimbu.ts` and add the following:
37+
For Deno, the following approach is recommended:
3838

39-
> ```ts
40-
> export * from 'https://deno.land/x/rimbu/bimap/mod.ts';
41-
> ```
39+
In the root folder of your project, create or edit a file called `import_map.json` with the following contents (where you should replace `x.y.z` with the desired version of Rimbu):
4240

43-
Or using a pinned version (`x.y.z`):
41+
```json
42+
{
43+
"imports": {
44+
"@rimbu/": "https://deno.land/x/rimbu@x.y.z/"
45+
}
46+
}
47+
```
48+
49+
**Note: The trailing slashes are important!**
50+
51+
In this way you can use relative imports from Rimbu in your code, like so:
4452

45-
> ```ts
46-
> export * from 'https://deno.land/x/rimbu/bimap@x.y.z/mod.ts';
47-
> ```
53+
```ts
54+
import { List } from '@rimbu/core/mod.ts';
55+
import { HashMap } from '@rimbu/hashed/mod.ts';
56+
```
4857

49-
Then import what you need from `rimbu.ts`:
58+
Note that for sub-packages, due to conversion limitations it is needed to import the `index.ts` instead of `mod.ts`, like so:
5059

5160
```ts
52-
import { HashBiMultiMap } from './rimbu.ts';
61+
import { HashMap } from '@rimbu/hashed/map/index.ts';
5362
```
5463

55-
Because Rimbu uses complex types, it's recommended to use the `--no-check` flag (your editor should already have checked your code) and to specify a `tsconfig.json` file with the settings described below.
64+
To run your script (let's assume the entry point is in `src/main.ts`):
65+
66+
`deno run --import-map import_map.json src/main.ts`
5667

57-
Running your script then becomes:
68+
Because Rimbu uses advanced types, this may slow down the type checking part when running your code. If you're able to rely on your code editor to provide type errors, you can skip the Deno type check using the `--no-check` flag:
5869

59-
> `deno run --no-check --config tsconfig.json <your-script>.ts`
70+
`deno run --import-map import_map.json --no-check src/main.ts`
6071

6172
## Usage
6273

@@ -78,7 +89,7 @@ Feel very welcome to contribute to further improve Rimbu. Please read our [Contr
7889

7990
## Contributors
8091

81-
<img src = "https://contrib.rocks/image?repo=vitoke/iternal"/>
92+
<img src = "https://contrib.rocks/image?repo=rimbu-org/rimbu"/>
8293

8394
Made with [contributors-img](https://contrib.rocks).
8495

0 commit comments

Comments
 (0)