inillucent 1.0.29 → 1.0.30

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.
Files changed (3) hide show
  1. package/README.md +133 -51
  2. package/package.json +6 -6
  3. package/resolve.mjs +1 -1
package/README.md CHANGED
@@ -1,27 +1,48 @@
1
1
  # inillucent
2
2
 
3
- An embedded SQL database that speaks SQLite's dialect on its own storage, with
4
- full-text and vector search built in — the job of PostgreSQL + pgvector + an
5
- embedding server, in one process and one file.
3
+ inillucent is an embedded SQL database. It speaks SQLite's dialect on its own storage, and it has
4
+ keyword search and vector search built in. One `.rdb` file holds the tables and the search indexes,
5
+ and one process reads and writes it.
6
+
7
+ This npm package installs the four inillucent programs and a small JavaScript API that runs them.
8
+
9
+ ## Install
6
10
 
7
11
  ```sh
8
12
  npm install -g inillucent
9
- # or, without installing anything permanently:
13
+ ```
14
+
15
+ Or run a program once without installing it:
16
+
17
+ ```sh
10
18
  npx inillucent help
11
19
  ```
12
20
 
13
- No native build step and no postinstall download: the binaries ship as
14
- per-platform packages that npm installs only where they run, so `npm ci` works
15
- offline and behind a proxy.
21
+ The package needs Node 18 or later. There is no install script and nothing downloads at install
22
+ time. The programs come in one extra package per platform, listed as optional dependencies. npm
23
+ installs only the one that matches your machine, so `npm ci` works offline and behind a registry
24
+ proxy.
25
+
26
+ | Platform | Package npm installs |
27
+ |---|---|
28
+ | Windows, x64 | `@blackrainbowlabs/cli-win32-x64` |
29
+ | macOS, Apple silicon | `@blackrainbowlabs/cli-darwin-arm64` |
30
+ | macOS, Intel | `@blackrainbowlabs/cli-darwin-x64` |
31
+ | Linux, x64 | `@blackrainbowlabs/cli-linux-x64` |
32
+ | Linux, arm64 | `@blackrainbowlabs/cli-linux-arm64` |
33
+
34
+ Each platform package holds the four programs in `bin/`, the C library in `lib/`, and its header
35
+ `inillucent_driver.h` in `include/`. If you installed with `--no-optional`, install the platform
36
+ package by name, for example `npm install @blackrainbowlabs/cli-linux-x64`.
16
37
 
17
- ## Four programs
38
+ ## The four programs
18
39
 
19
- | | |
40
+ | Program | What it is |
20
41
  |---|---|
21
- | `inillucent` | the command line: `query`, `exec`, `describe`, `import`, `export`, `search`, and twenty more |
22
- | `inillucent-shell` | an interactive shell shaped like `sqlite3`, with all 63 of its dot commands |
23
- | `inillucent-mcp` | the same commands served to an AI agent over MCP |
24
- | `inillucent-migrate` | builds an inillucent database from a SQLite file |
42
+ | `inillucent` | the command line: 30 commands, such as `query`, `exec`, `describe`, `import`, `export` and `search` |
43
+ | `inillucent-shell` | an interactive shell that works like `sqlite3`, with 63 of its 65 dot commands |
44
+ | `inillucent-mcp` | an MCP server: 28 of the same commands served to an AI agent |
45
+ | `inillucent-migrate` | builds a database from a legacy retrieval index. `inillucent migrate` copies a SQLite file or a PostgreSQL or MySQL database |
25
46
 
26
47
  ## From a shell
27
48
 
@@ -34,69 +55,130 @@ inillucent --db app.rdb describe notes
34
55
  inillucent help
35
56
  ```
36
57
 
37
- Exit codes carry meaning: `0` success, `1` failed, `2` a command line nobody
38
- could act on, and **`3` a construct the engine has not built yet** — so a script
39
- can branch on "not yet" without matching on a message.
58
+ `--params` binds `?1`, `?2` and so on, in order. Add `--output json` to any command to get a JSON
59
+ object a program can parse.
40
60
 
41
- ## From Node
61
+ | Exit code | Meaning |
62
+ |---|---|
63
+ | `0` | success |
64
+ | `1` | the command failed |
65
+ | `2` | the command line could not be read, such as an unknown command |
66
+ | `3` | the engine has not built that feature. Rewording the SQL does not help |
67
+
68
+ ## From JavaScript
42
69
 
43
70
  ```js
44
71
  import { query, inillucent } from 'inillucent';
45
72
 
46
- const rows = await query('SELECT id, body FROM notes WHERE id > ?1', {
47
- db: 'app.rdb',
48
- params: [3],
49
- });
50
- // [{ id: 4, body: 'hello' }]
73
+ await inillucent('exec', { db: 'app.rdb', sql: 'INSERT INTO notes (body) VALUES (?1)', params: ['world'] });
74
+
75
+ const rows = await query('SELECT id, body FROM notes WHERE id > ?1', { db: 'app.rdb', params: [1] });
76
+ // [ { id: 2, body: 'world' } ]
51
77
 
52
78
  const described = await inillucent('describe', { db: 'app.rdb', table: 'notes' });
53
79
  console.log(described.ddl, described.indexes, described.row_count_in_table);
54
80
  ```
55
81
 
56
- Each call is a process, so this is the right tool for the dozen calls a build
57
- script or a tool wrapper makes and the wrong one for a loop over a million rows.
58
- For that, write a binding over the C ABI — the header ships in this package's
59
- platform dependency under `include/`, and
60
- [`drivers/README.md`](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/drivers/README.md)
61
- is written to be followed.
82
+ Each call starts one `inillucent` process with `--output json` and parses the object it prints.
83
+ `params` travels to the process on standard input, so a large value does not hit the operating
84
+ system's limit on command line length.
85
+
86
+ Starting a process costs time on every call. This package suits a build script or a tool wrapper
87
+ that makes a dozen calls. It does not suit a loop over a million rows. For that, write a binding over
88
+ the C library in the platform package. The
89
+ [driver guide](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/drivers/README.md)
90
+ explains how.
91
+
92
+ Because each call is its own process, this package has no connection object and no transaction that
93
+ spans two calls. To run several statements as one transaction, use the `batch` command:
94
+ `inillucent('batch', { db, sql: 'INSERT ...; UPDATE ...' })`.
95
+
96
+ ### Values
97
+
98
+ | JavaScript value | Bound as |
99
+ |---|---|
100
+ | `null` or `undefined` | `NULL` |
101
+ | a number | `INTEGER` or `REAL`. `-0` keeps its sign |
102
+ | `NaN`, `Infinity` | refused with a `TypeError`, because SQL has no value for them |
103
+ | a string | `TEXT` |
104
+ | a `Uint8Array` | `BLOB` |
105
+
106
+ `query()` returns a BLOB column as a `Uint8Array`, so bytes read by one query can be bound into the
107
+ next.
108
+
109
+ ## Errors
110
+
111
+ ```js
112
+ const result = await inillucent('query', { db: 'app.rdb', sql: 'SELECT * FROM absent' });
113
+ // result.ok === false, result.status === 'not_found', result.message === 'no such table: absent'
114
+
115
+ try {
116
+ await query('SELECT * FROM absent', { db: 'app.rdb' });
117
+ } catch (error) {
118
+ console.log(error.status); // 'not_found'
119
+ }
120
+ ```
121
+
122
+ `inillucent()` returns a refusal as its result object with `ok: false`. `query()` throws an `Error`
123
+ with three extra fields: `status`, `message` and `feature`. Both throw only when the program could
124
+ not be run at all.
125
+
126
+ `status` is one of thirteen names: `unsupported`, `syntax`, `not_found`, `constraint`, `readonly`,
127
+ `busy`, `interrupted`, `corrupt`, `io`, `full`, `too_big`, `invalid_state` and `internal`.
128
+
129
+ `unsupported` means the engine has not built that feature, and `feature` names it. The SQL is not
130
+ wrong, and a different spelling fails the same way. Check `inillucent capabilities` before you
131
+ write an unusual statement.
62
132
 
63
- ## For an agent
133
+ ## For an AI agent
134
+
135
+ MCP, the Model Context Protocol, is how an AI agent calls tools. Add `inillucent-mcp` to an MCP
136
+ client's configuration:
64
137
 
65
138
  ```json
66
139
  {
67
140
  "mcpServers": {
68
141
  "inillucent": {
69
142
  "command": "npx",
70
- "args": ["-y", "inillucent-mcp", "--db", "app.rdb"]
143
+ "args": ["-y", "-p", "inillucent", "inillucent-mcp", "--db", "app.rdb"]
71
144
  }
72
145
  }
73
146
  }
74
147
  ```
75
148
 
76
- 27 tools, generated from the same command table the CLI reads, so the two can
77
- never drift. `--readonly` refuses every statement that changes something, and
78
- `--root DIR` refuses every path outside a directory.
79
-
80
- ## Licence
81
-
82
- MIT. Source: <https://github.com/Black-Rainbow-Labs/Inillucent>
149
+ `inillucent-mcp` serves 28 of the command line's commands as MCP tools. The tools are generated from
150
+ the same command table as the command line. `--readonly` refuses every statement that changes data.
151
+ `--root DIR` refuses every path outside `DIR`.
83
152
 
84
153
  ## The API
85
154
 
86
- Every method this binding has. The worked example each one appears in is the link; nothing here is
87
- a summary of a method that does not exist, because
88
- `cargo test -p inillucent-compat --test documentation` reads this table and fails on a name the
89
- binding source does not declare.
155
+ `cargo test -p inillucent-compat --test tooling documentation::` reads this table and fails if a name in the
156
+ first column is not declared in `index.mjs` or `resolve.mjs`.
90
157
 
91
158
  | what | one line |
92
159
  |---|---|
93
- | `inillucent(command, options)` | run one command of the command line and return its parsed JSON. `options.db` names the file, `options.args` the rest. |
94
- | `query(sql, options)` | run one `SELECT` and return its rows. `options.params` binds `?1`, `?2`; `options.limit` caps the rows kept. |
95
- | `resolveBinary(program)` | the path to one of the four programs on this platform, from the platform package npm installed. |
96
- | `platformPackage()` | the name of the platform package this machine needs, which is what an install failure should name. |
97
- | `PROGRAMS` | the four programs and what each is for, as an object. |
98
-
99
- Every call goes through the command line rather than through the C ABI: the four programs are what
100
- the platform package ships, and `--output json` is the same object every other binding sees. That
101
- is why there is no `Connection` here and no transaction - a command is one process, and a
102
- transaction that spanned two of them would be a transaction nothing held open.
160
+ | `inillucent(command, options)` | runs one command and resolves to its parsed JSON result. `options.db` names the file. Every other key becomes a flag: `{ table: 'notes' }` is `--table notes`, `true` is a bare flag. |
161
+ | `query(sql, options)` | runs one query and resolves to its rows as objects keyed by column name. `options` takes `db`, `params` and `limit`. Throws on a refusal. |
162
+ | `resolveBinary(program)` | returns the path to one of the four programs on this machine. `INILLUCENT_BIN` overrides it. |
163
+ | `platformPackage()` | returns the platform package this machine needs, or `null` when there is none. |
164
+ | `PROGRAMS` | an object naming the four programs. |
165
+
166
+ A result object from `inillucent()` has these fields on success: `ok`, `command`, `columns`, `rows`,
167
+ `row_count`, `total`, `more`, `changes`, `last_insert_rowid`, `elapsed_ms` and `text`. Some commands
168
+ add their own, such as `ddl` and `indexes` from `describe`. `total` counts every row the statement
169
+ produced, even when `limit` cut the rows returned.
170
+
171
+ The `query` command returns at most 200 rows unless you pass `limit`. `limit: 0` returns every row.
172
+ `more: true` in the result means rows were left out.
173
+
174
+ `INILLUCENT_BIN` names an `inillucent` binary to use in place of the platform package. The other
175
+ three programs are then looked for in the same folder.
176
+
177
+ ## More
178
+
179
+ - [Getting started](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/docs/getting-started.md)
180
+ - [SQL support](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/docs/sql.md)
181
+ - [Vector and keyword search](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/docs/vector-search.md)
182
+ - [Glossary](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/docs/glossary.md)
183
+
184
+ MIT licence. Source: <https://github.com/Black-Rainbow-Labs/Inillucent>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "inillucent",
3
- "version": "1.0.29",
3
+ "version": "1.0.30",
4
4
  "description": "Embedded SQL database with full-text and vector search, an MCP server, and a sqlite3-shaped shell. No native build step: the binaries ship as platform packages.",
5
5
  "keywords": [
6
6
  "database",
@@ -43,10 +43,10 @@
43
43
  "README.md"
44
44
  ],
45
45
  "optionalDependencies": {
46
- "@blackrainbowlabs/cli-win32-x64": "1.0.29",
47
- "@blackrainbowlabs/cli-darwin-arm64": "1.0.29",
48
- "@blackrainbowlabs/cli-darwin-x64": "1.0.29",
49
- "@blackrainbowlabs/cli-linux-x64": "1.0.29",
50
- "@blackrainbowlabs/cli-linux-arm64": "1.0.29"
46
+ "@blackrainbowlabs/cli-win32-x64": "1.0.30",
47
+ "@blackrainbowlabs/cli-darwin-arm64": "1.0.30",
48
+ "@blackrainbowlabs/cli-darwin-x64": "1.0.30",
49
+ "@blackrainbowlabs/cli-linux-x64": "1.0.30",
50
+ "@blackrainbowlabs/cli-linux-arm64": "1.0.30"
51
51
  }
52
52
  }
package/resolve.mjs CHANGED
@@ -40,7 +40,7 @@ export const PROGRAMS = {
40
40
  inillucent: 'the command line: query, exec, describe, import, export, search',
41
41
  'inillucent-shell': 'the interactive sqlite3-shaped shell',
42
42
  'inillucent-mcp': 'the MCP server, for an agent',
43
- 'inillucent-migrate': 'builds an inillucent database from a SQLite file',
43
+ 'inillucent-migrate': 'builds an inillucent database from a legacy retrieval index',
44
44
  };
45
45
 
46
46
  /**