@antelopejs/rethinkdb 1.4.0 → 1.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -129
- package/package.json +11 -7
package/README.md
CHANGED
|
@@ -1,172 +1,136 @@
|
|
|
1
1
|
# @antelopejs/rethinkdb
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<a href="https://www.npmjs.com/package/@antelopejs/rethinkdb"><img alt="
|
|
5
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/rethinkdb
|
|
4
|
+
<a href="https://www.npmjs.com/package/@antelopejs/rethinkdb"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/rethinkdb?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
|
+
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/rethinkdb?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
6
|
<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
|
|
7
|
-
<a href="https://antelopejs.com/
|
|
7
|
+
<a href="https://interfaces.antelopejs.com/docs/database"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
|
|
8
8
|
</div>
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
## Installation
|
|
13
|
-
|
|
14
|
-
```bash
|
|
15
|
-
ajs project modules add @antelopejs/rethinkdb
|
|
16
|
-
```
|
|
10
|
+
The RethinkDB backend of AntelopeJS: it runs the database interface's queries on RethinkDB with [`rethinkdb-ts`](https://github.com/rethinkdb/rethinkdb-ts), and exposes that driver to modules that need it directly.
|
|
17
11
|
|
|
18
12
|
## Interfaces
|
|
19
13
|
|
|
20
|
-
|
|
14
|
+
| Interface | Documentation |
|
|
15
|
+
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
16
|
+
| [`@antelopejs/interface-database`](https://github.com/AntelopeJS/interface-database) | [Database](https://interfaces.antelopejs.com/docs/database) |
|
|
17
|
+
| [`@antelopejs/interface-rethinkdb`](https://github.com/AntelopeJS/interface-rethinkdb) | [RethinkDB](https://interfaces.antelopejs.com/docs/rethinkdb/introduction) |
|
|
21
18
|
|
|
22
|
-
|
|
23
|
-
- **Database Interface**: Offers a standardized database abstraction layer
|
|
19
|
+
Schemas, tables, queries, change feeds and atomic mutations are documented on the database interface pages.
|
|
24
20
|
|
|
25
|
-
|
|
21
|
+
## Install
|
|
26
22
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
| Database | `ajs module imports add database` | [Documentation](https://github.com/AntelopeJS/interface-database) |
|
|
31
|
-
|
|
32
|
-
## Overview
|
|
33
|
-
|
|
34
|
-
The AntelopeJS RethinkDB module provides functionality for interacting with RethinkDB:
|
|
23
|
+
```bash
|
|
24
|
+
ajs project modules add @antelopejs/rethinkdb
|
|
25
|
+
```
|
|
35
26
|
|
|
36
|
-
|
|
37
|
-
- Common database operations through the Database interface
|
|
27
|
+
The command writes the module's default configuration: a connection pool to `127.0.0.1:28015` as `admin`.
|
|
38
28
|
|
|
39
29
|
## Configuration
|
|
40
30
|
|
|
41
|
-
The
|
|
31
|
+
The module connects either through a connection pool (`pool`) or through a single connection (`connection`). When both are set, `pool` wins.
|
|
32
|
+
|
|
33
|
+
```typescript [antelope.config.ts]
|
|
34
|
+
import { defineConfig } from "@antelopejs/interface-core/config";
|
|
35
|
+
|
|
36
|
+
export default defineConfig({
|
|
37
|
+
name: "my-project",
|
|
38
|
+
modules: {
|
|
39
|
+
rethinkdb: {
|
|
40
|
+
source: {
|
|
41
|
+
type: "package",
|
|
42
|
+
package: "@antelopejs/rethinkdb",
|
|
43
|
+
version: "^1.4.0",
|
|
44
|
+
},
|
|
45
|
+
config: {
|
|
46
|
+
pool: {
|
|
47
|
+
host: "127.0.0.1",
|
|
48
|
+
port: 28015,
|
|
49
|
+
user: "admin",
|
|
50
|
+
password: "",
|
|
51
|
+
pool: true,
|
|
52
|
+
cursor: false,
|
|
53
|
+
silent: true,
|
|
54
|
+
discovery: true,
|
|
55
|
+
},
|
|
56
|
+
},
|
|
57
|
+
},
|
|
58
|
+
},
|
|
59
|
+
});
|
|
60
|
+
```
|
|
42
61
|
|
|
43
|
-
|
|
62
|
+
For a single connection:
|
|
44
63
|
|
|
45
64
|
```typescript
|
|
46
|
-
|
|
47
|
-
{
|
|
48
|
-
|
|
49
|
-
port: 28015, // The port to connect on
|
|
50
|
-
db: "test", // The default database
|
|
51
|
-
user: "admin", // The user account to connect as
|
|
52
|
-
password: "", // The password for the user account
|
|
53
|
-
timeout: 20, // Timeout period in seconds for the connection to be opened
|
|
54
|
-
ssl: false // Use SSL for connection
|
|
55
|
-
}
|
|
65
|
+
config: {
|
|
66
|
+
connection: { host: "127.0.0.1", port: 28015, user: "admin", password: "" },
|
|
67
|
+
},
|
|
56
68
|
```
|
|
57
69
|
|
|
58
|
-
|
|
70
|
+
| Key | Description |
|
|
71
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------- |
|
|
72
|
+
| `pool` | `rethinkdb-ts` pool options (`RPoolConnectionOptions`), passed to `r.connectPool()`. |
|
|
73
|
+
| `connection` | `rethinkdb-ts` connection options (`RConnectionOptions`), passed to `r.connect()`. Used when `pool` is unset. |
|
|
59
74
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
db: "test", // The default database
|
|
66
|
-
user: "admin", // The user account to connect as
|
|
67
|
-
password: "", // The password for the user account
|
|
68
|
-
timeout: 20, // Timeout period in seconds
|
|
69
|
-
maxConnections: 10, // Maximum number of connections in the pool
|
|
70
|
-
bufferSize: 50, // Buffer size for the pool
|
|
71
|
-
maxBufferSize: 100, // Maximum buffer size
|
|
72
|
-
discovery: false, // Enable server discovery
|
|
73
|
-
servers: [] // Additional servers for connection
|
|
74
|
-
}
|
|
75
|
-
```
|
|
75
|
+
The module refuses to start when neither key is set. The option types come from [`rethinkdb-ts`](https://github.com/rethinkdb/rethinkdb-ts).
|
|
76
|
+
|
|
77
|
+
## Quick start
|
|
78
|
+
|
|
79
|
+
In the module that stores data, add the database interface:
|
|
76
80
|
|
|
77
|
-
|
|
81
|
+
```bash
|
|
82
|
+
pnpm add @antelopejs/interface-database
|
|
83
|
+
```
|
|
78
84
|
|
|
79
|
-
The
|
|
85
|
+
Then follow the [database interface guide](https://framework.antelopejs.com/docs/guides/database) to declare a schema and query it. The same code runs on [`@antelopejs/mongodb`](https://github.com/AntelopeJS/mongodb).
|
|
80
86
|
|
|
81
|
-
-
|
|
82
|
-
- Connection pool using `r.connectPool()` with `RPoolConnectionOptions`
|
|
87
|
+
To use the driver directly instead, add `@antelopejs/interface-rethinkdb` and read its [documentation](https://interfaces.antelopejs.com/docs/rethinkdb/introduction).
|
|
83
88
|
|
|
84
|
-
##
|
|
89
|
+
## Storage layout
|
|
85
90
|
|
|
86
|
-
Every table has a `tenant_id` index
|
|
87
|
-
|
|
91
|
+
- Each schema is a RethinkDB database, and each schema table is a table in it. Every table has a `tenant_id` index that scopes it to one instance.
|
|
92
|
+
- Each declared index `<name>` becomes a `<name>__i` index led by the instance. An index declared with `crossInstance: true` also gets an unprefixed `<name>` index for `CROSS_INSTANCE` queries; without it, those queries scan the table and log a one-time warning. Index names ending in `__i` are reserved.
|
|
93
|
+
- Schema initialization creates missing databases, tables and indexes, retries up to five times, and waits for the indexes before the schema accepts queries.
|
|
88
94
|
|
|
89
|
-
|
|
90
|
-
indexes, `[tenant_id, value]` for single-field indexes, and one
|
|
91
|
-
`[tenant_id, element]` entry per element for `multi` indexes. Scoped `getAll`
|
|
92
|
-
and `between` use it.
|
|
93
|
-
- `<name>`, the unprefixed index, only when the index is declared with
|
|
94
|
-
`crossInstance: true`. `CROSS_INSTANCE` reads on the index use it.
|
|
95
|
+
Version 1.4 added the `<name>__i` indexes. The first boot after an upgrade builds them, which takes longer on large tables. The module never drops an index: drop the old ones you no longer need by hand, for example `r.db("<schema>").table("<table>").indexDrop("<name>")`.
|
|
95
96
|
|
|
96
|
-
|
|
97
|
-
`distinct(field)` and `lookup` on an index that is not declared with
|
|
98
|
-
`crossInstance: true` still work, but scan the table instead of using an index.
|
|
99
|
-
The module logs a warning the first time a process runs such a query for each
|
|
100
|
-
schema, table and index. Plain filters never log a warning.
|
|
97
|
+
## Documentation
|
|
101
98
|
|
|
102
|
-
|
|
99
|
+
- [Database](https://interfaces.antelopejs.com/docs/database): the `@antelopejs/interface-database` contract this module implements
|
|
100
|
+
- [RethinkDB](https://interfaces.antelopejs.com/docs/rethinkdb/introduction): the `@antelopejs/interface-rethinkdb` contract this module implements
|
|
101
|
+
- [Configuration](https://framework.antelopejs.com/docs/concepts/configuration): module sources, `config` blocks and config variables in `antelope.config.ts`
|
|
103
102
|
|
|
104
|
-
|
|
105
|
-
the index returns a document once per matching key or `multi` entry.
|
|
106
|
-
- `orderBy` also returns documents that lack the sorted field, like scoped
|
|
107
|
-
`orderBy`, while the index leaves them out.
|
|
103
|
+
## Compatibility
|
|
108
104
|
|
|
109
|
-
|
|
110
|
-
|
|
105
|
+
| Package | Supported range |
|
|
106
|
+
| --------------------------------- | ---------------- |
|
|
107
|
+
| `@antelopejs/interface-database` | `^0.1.8` |
|
|
108
|
+
| `@antelopejs/interface-rethinkdb` | `>=0.0.5 <1.0.0` |
|
|
109
|
+
| `@antelopejs/interface-core` | `>=0.1.1 <1.0.0` |
|
|
111
110
|
|
|
112
|
-
|
|
113
|
-
that lack the sorted field, and scoped `orderBy` keeps returning them.
|
|
111
|
+
The module is developed and tested against `@antelopejs/core` `^1.13.4` on Node.js 24, with `rethinkdb-ts` `^2.7.0` and RethinkDB 2.4.
|
|
114
112
|
|
|
115
|
-
|
|
116
|
-
missing, and ignores "already exists" errors when another process booting at
|
|
117
|
-
the same time creates them first. It retries a failed initialization up to five
|
|
118
|
-
times with exponential backoff, and waits until the indexes it manages are
|
|
119
|
-
ready before the schema accepts queries. RethinkDB builds indexes in the
|
|
120
|
-
background without blocking writes.
|
|
113
|
+
## Contributing
|
|
121
114
|
|
|
122
|
-
|
|
115
|
+
The tests need a RethinkDB server on `127.0.0.1:28015`. Start the one CI uses:
|
|
123
116
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
117
|
+
```bash
|
|
118
|
+
docker compose -f .github/release-services.yml up -d --wait
|
|
119
|
+
```
|
|
127
120
|
|
|
128
|
-
|
|
129
|
-
indexes stay in place: they keep serving cross-instance queries for indexes
|
|
130
|
-
declared with `crossInstance: true`, and are unused otherwise. Drop unused ones
|
|
131
|
-
by hand to save storage and write time:
|
|
121
|
+
Then run the checks:
|
|
132
122
|
|
|
133
|
-
```
|
|
134
|
-
|
|
123
|
+
```bash
|
|
124
|
+
pnpm install
|
|
125
|
+
pnpm lint
|
|
126
|
+
pnpm format:check
|
|
127
|
+
pnpm typecheck
|
|
128
|
+
pnpm knip
|
|
129
|
+
pnpm test # build, then ajs module test
|
|
135
130
|
```
|
|
136
131
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
`table.atomicMutation(key, request).run()` checks one primary key, its instance,
|
|
140
|
-
and the requested condition inside a deterministic native RethinkDB `replace`
|
|
141
|
-
function. It never inserts a missing record or retries a submitted mutation.
|
|
142
|
-
`CROSS_INSTANCE` and selections are not supported.
|
|
143
|
-
|
|
144
|
-
Revision-based updates replace the supplied top-level fields, including complete
|
|
145
|
-
nested objects, and install `nextRevision` in the same write. Revision-based
|
|
146
|
-
deletes remove the matching record. The `{ kind: "missing" }` expected revision
|
|
147
|
-
matches an absent field on an existing record, not a stored `null` value. Callers
|
|
148
|
-
must use fresh revision tokens and must not reuse an identity across incarnations.
|
|
149
|
-
|
|
150
|
-
`deleteIfEqual` checks one scalar field, including a `Date`, before deleting the
|
|
151
|
-
record. It does not provide revision-based protection against a value changing
|
|
152
|
-
and later changing back. Retention callers must keep their cutoff fixed and
|
|
153
|
-
re-evaluate eligibility when they observe a different value.
|
|
154
|
-
|
|
155
|
-
The result is `applied`, `not-applied`, or `unknown`. Missing records, wrong
|
|
156
|
-
instances, and condition mismatches return `not-applied`. Lost acknowledgements,
|
|
157
|
-
indeterminate driver errors, untyped write-result errors, and malformed
|
|
158
|
-
acknowledgements return `unknown`; callers must reconcile them rather than infer
|
|
159
|
-
that no write occurred. Invalid requests and definite typed query-validation
|
|
160
|
-
errors throw. Ordinary insert/update/replace/delete operations reject write
|
|
161
|
-
errors, including duplicate primary keys; a multi-record write may have partially
|
|
162
|
-
succeeded before it reports an error.
|
|
163
|
-
|
|
164
|
-
This implementation requires `@antelopejs/interface-database` version `0.1.6`
|
|
165
|
-
or later within the supported range. Its shared real-backend conformance suite
|
|
166
|
-
runs automatically through `ajs module test`, alongside this provider's native
|
|
167
|
-
acknowledgement, storage, and fault tests. Install the published dependencies
|
|
168
|
-
with `pnpm install --frozen-lockfile`; no local artifact is required.
|
|
132
|
+
The tests also run the shared conformance suite of `@antelopejs/interface-database`. Read the [contribution guidelines](CONTRIBUTING.md) before opening a pull request.
|
|
169
133
|
|
|
170
134
|
## License
|
|
171
135
|
|
|
172
|
-
|
|
136
|
+
[Apache-2.0](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/rethinkdb",
|
|
3
|
-
"version": "1.4.
|
|
4
|
-
"description": "RethinkDB
|
|
3
|
+
"version": "1.4.1",
|
|
4
|
+
"description": "RethinkDB backend for AntelopeJS, implementing the Database and RethinkDB interfaces with rethinkdb-ts",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
7
7
|
"database",
|
|
@@ -9,6 +9,10 @@
|
|
|
9
9
|
"realtime",
|
|
10
10
|
"rethinkdb"
|
|
11
11
|
],
|
|
12
|
+
"homepage": "https://interfaces.antelopejs.com/docs/database",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/AntelopeJS/rethinkdb/issues"
|
|
15
|
+
},
|
|
12
16
|
"license": "Apache-2.0",
|
|
13
17
|
"repository": {
|
|
14
18
|
"type": "git",
|
|
@@ -35,16 +39,16 @@
|
|
|
35
39
|
"knip": "knip"
|
|
36
40
|
},
|
|
37
41
|
"dependencies": {
|
|
38
|
-
"@antelopejs/interface-core": ">=0.
|
|
39
|
-
"@antelopejs/interface-database": "^0.1.
|
|
40
|
-
"@antelopejs/interface-rethinkdb": ">=0.0.
|
|
42
|
+
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
43
|
+
"@antelopejs/interface-database": "^0.1.10",
|
|
44
|
+
"@antelopejs/interface-rethinkdb": ">=0.0.6 <1.0.0",
|
|
41
45
|
"chai": "^4.5.0",
|
|
42
46
|
"reflect-metadata": "^0.2.2",
|
|
43
47
|
"rethinkdb-ts": "^2.7.0"
|
|
44
48
|
},
|
|
45
49
|
"devDependencies": {
|
|
46
|
-
"@antelopejs/core": "^1.
|
|
47
|
-
"@antelopejs/tooling-configs": "^0.0.
|
|
50
|
+
"@antelopejs/core": "^1.16.0",
|
|
51
|
+
"@antelopejs/tooling-configs": "^0.0.9",
|
|
48
52
|
"@types/chai": "^4.3.20",
|
|
49
53
|
"@types/mocha": "^10.0.10",
|
|
50
54
|
"@types/node": "^22.19.15",
|