@walkeros/server-destination-sqlite 4.1.0-next-1778668930820 → 4.1.0

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 (4) hide show
  1. package/CHANGELOG.md +140 -0
  2. package/README.md +32 -164
  3. package/dist/walkerOS.json +3 -2
  4. package/package.json +6 -5
package/CHANGELOG.md ADDED
@@ -0,0 +1,140 @@
1
+ # @walkeros/server-destination-sqlite
2
+
3
+ ## 4.1.0
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [e155ff8]
8
+ - Updated dependencies [e800974]
9
+ - Updated dependencies [e155ff8]
10
+ - Updated dependencies [1a8f2d7]
11
+ - Updated dependencies [1a8f2d7]
12
+ - Updated dependencies [b276173]
13
+ - Updated dependencies [dd9f5ad]
14
+ - Updated dependencies [c60ef35]
15
+ - Updated dependencies [adeebea]
16
+ - Updated dependencies [13aaeaa]
17
+ - Updated dependencies [e800974]
18
+ - Updated dependencies [adeebea]
19
+ - Updated dependencies [e800974]
20
+ - Updated dependencies [e800974]
21
+ - Updated dependencies [058f7ed]
22
+ - Updated dependencies [28a8ac2]
23
+ - Updated dependencies [fd6076e]
24
+ - @walkeros/core@4.1.0
25
+ - @walkeros/server-core@4.1.0
26
+
27
+ ## 4.0.2
28
+
29
+ ### Patch Changes
30
+
31
+ - Updated dependencies [a6a0ea7]
32
+ - @walkeros/core@4.0.2
33
+ - @walkeros/server-core@4.0.2
34
+
35
+ ## 4.0.1
36
+
37
+ ### Patch Changes
38
+
39
+ - cc3bbd0: Add the `setup()` lifecycle. Run `walkeros setup destination.<name>`
40
+ to create the events table with the canonical walkerOS Event v4 schema and
41
+ apply pragmas (`journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`,
42
+ `temp_store=MEMORY`). Setup is idempotent and detects drift via
43
+ `PRAGMA table_info` (logs `WARN setup.drift`, never auto-mutates).
44
+
45
+ The `settings.sqlite.schema: 'auto' | 'manual'` setting is deprecated and will
46
+ be removed in the next major. Migration: `schema: 'auto'` to `setup: true`,
47
+ `schema: 'manual'` to `setup: false`. The deprecated form still works and
48
+ emits a one-time WARN through the destination logger.
49
+
50
+ - Updated dependencies [381dfe7]
51
+ - Updated dependencies [1524275]
52
+ - Updated dependencies [03d7055]
53
+ - @walkeros/core@4.0.1
54
+ - @walkeros/server-core@4.0.1
55
+
56
+ ## 4.0.0
57
+
58
+ ### Major Changes
59
+
60
+ - 93ea9c4: Event model v4: breaking changes to the `Event`, `Source`, and
61
+ `Entity` shapes.
62
+ - `event.id` is now a W3C span_id (16 lowercase hex chars), generated by the
63
+ collector. Reference: W3C Trace Context (W3C Recommendation, January 2020).
64
+ - `event.version`, `event.group`, `event.count` are removed.
65
+ - `source.type` is now the source kind (e.g. `browser`, `gtag`, `mcp`, `cli`).
66
+ New `source.platform` holds the runtime (`web` | `server` | `app` | ...).
67
+ - `source.id` and `source.previous_id` are removed.
68
+ - Browser source now sets `source.url` and `source.referrer`.
69
+ - MCP source sets `source.tool` per emission. CLI source sets
70
+ `source.command`.
71
+ - `Entity.nested` and `Entity.context` are now optional. Root `event.nested`
72
+ and `event.context` remain required.
73
+ - Each source self-registers via TypeScript module augmentation of `SourceMap`
74
+ in `@walkeros/core`.
75
+ - App-side coordination (`/workspaces/developer/app`) is a follow-up plan, not
76
+ part of this release. Telemetry from v4 CLI/MCP will not validate against
77
+ the existing app schema until that follow-up ships.
78
+ - `Mapping.Rule.skip` is renamed to `Mapping.Rule.silent`. Customer flow.json
79
+ configs using `skip: true` in mapping rules must rename to `silent: true`.
80
+ Hard cut: no legacy alias, the field is gone.
81
+
82
+ ### Patch Changes
83
+
84
+ - Updated dependencies [93ea9c4]
85
+ - Updated dependencies [465775c]
86
+ - Updated dependencies [942a7fe]
87
+ - Updated dependencies [cfc7469]
88
+ - Updated dependencies [8e06b1f]
89
+ - Updated dependencies [3d50dd6]
90
+ - Updated dependencies [1ef33d9]
91
+ - @walkeros/core@4.0.0
92
+ - @walkeros/server-core@4.0.0
93
+
94
+ ## 3.4.2
95
+
96
+ ### Patch Changes
97
+
98
+ - @walkeros/core@3.4.2
99
+ - @walkeros/server-core@3.4.2
100
+
101
+ ## 3.4.1
102
+
103
+ ### Patch Changes
104
+
105
+ - Updated dependencies [12adf24]
106
+ - Updated dependencies [75aa26b]
107
+ - @walkeros/core@3.4.1
108
+ - @walkeros/server-core@3.4.1
109
+
110
+ ## 3.4.0
111
+
112
+ ### Minor Changes
113
+
114
+ - 74940cc: Add `@walkeros/server-destination-sqlite`: server destination that
115
+ persists walkerOS events to SQLite. One destination, two drivers behind a
116
+ single interface: `better-sqlite3` for local files and `:memory:`,
117
+ `@libsql/client` for remote Turso / libSQL / sqld. Driver is auto-selected
118
+ from the connection URL. Both SDKs are optional peer dependencies.
119
+ Auto-creates a canonical events table on init (opt-out via
120
+ `schema: 'manual'`), caches a prepared INSERT, closes the connection on
121
+ `destroy()`. Per-rule `mapping.settings.table` override supported.
122
+ - 724f97e: Migrate every step example in every walkerOS package to the
123
+ standardized `[callable, ...args][]` shape introduced in `@walkeros/core`.
124
+ Every step example's `out` is now an array of effect tuples whose first
125
+ element is the callable's public SDK name (`'gtag'`, `'analytics.track'`,
126
+ `'fbq'`, `'dataLayer.push'`, `'sendServer'`, `'fetch'`, `'trackClient.track'`,
127
+ `'amplitude.track'`, `'fs.writeFile'`, `'producer.send'`, `'client.xadd'`,
128
+ `'client.send'`, `'dataset.table.insert'`, etc.). Source examples use `'elb'`
129
+ as the callable; transformer examples use the reserved `'return'` keyword;
130
+ store examples use store-operation callables (`'get'`, `'set'`). Tests capture
131
+ real calls on each component's spy and assert against `example.out` directly —
132
+ the hardcoded `PACKAGE_CALLS` registry in the app is no longer consulted
133
+ (emptied; plan #3 removes it structurally).
134
+
135
+ ### Patch Changes
136
+
137
+ - Updated dependencies [74940cc]
138
+ - Updated dependencies [525f5d9]
139
+ - @walkeros/core@3.4.0
140
+ - @walkeros/server-core@3.4.0
package/README.md CHANGED
@@ -1,134 +1,37 @@
1
- # @walkeros/server-destination-sqlite
2
-
3
- Server-side SQLite destination for
4
- [walkerOS](https://github.com/elbwalker/walkerOS). Writes events to a local
5
- SQLite file (via `better-sqlite3`) or a remote Turso / libSQL / sqld database
6
- (via `@libsql/client`). Driver is auto-selected from the connection URL. Both
7
- SDKs are optional peer dependencies, install only what you need.
8
-
9
- ## Installation
10
-
11
- ```bash
12
- npm install @walkeros/server-destination-sqlite better-sqlite3
13
- # or for remote Turso / libSQL
14
- npm install @walkeros/server-destination-sqlite @libsql/client
15
- ```
16
-
17
- ## Quick Start
18
-
19
- Local file:
20
-
21
- ```json
22
- {
23
- "destinations": {
24
- "sqlite": {
25
- "package": "@walkeros/server-destination-sqlite",
26
- "config": {
27
- "settings": {
28
- "sqlite": {
29
- "url": "./events.db"
30
- }
31
- },
32
- "setup": true
33
- }
34
- }
35
- }
36
- }
37
- ```
38
-
39
- Remote Turso:
40
-
41
- ```json
42
- {
43
- "destinations": {
44
- "sqlite": {
45
- "package": "@walkeros/server-destination-sqlite",
46
- "config": {
47
- "settings": {
48
- "sqlite": {
49
- "url": "libsql://my-db.turso.io",
50
- "authToken": "$env.TURSO_TOKEN"
51
- }
52
- },
53
- "setup": true
54
- }
55
- }
56
- }
57
- }
58
- ```
1
+ <p align="left">
2
+ <a href="https://www.walkeros.io">
3
+ <img alt="walkerOS" title="walkerOS" src="https://www.walkeros.io/img/walkerOS_logo.svg" width="256px"/>
4
+ </a>
5
+ </p>
59
6
 
60
- ## Settings
61
-
62
- | Setting | Type | Required | Default | Description |
63
- | ------------------ | -------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
64
- | `sqlite.url` | `string` | Yes | `--` | Connection URL. `libsql://`, `http(s)://`, `ws(s)://` route to libSQL. Anything else is treated as a local file. Use `:memory:` for in-memory. |
65
- | `sqlite.authToken` | `string` | No | `--` | libSQL / Turso auth token. Ignored for local. |
66
- | `sqlite.table` | `string` | No | `events` | Target table name. |
67
- | `sqlite.schema` | `'auto' \| 'manual'` | **DEPRECATED** | `--` | Use `config.setup` instead. `auto` maps to `setup: true`, `manual` maps to `setup: false`. Removed in next major. |
68
-
69
- ## Per-rule mapping overrides
7
+ # @walkeros/server-destination-sqlite
70
8
 
71
- | Setting | Type | Description |
72
- | ------------------------ | -------- | ------------------------------------ |
73
- | `mapping.settings.table` | `string` | Override target table for this rule. |
9
+ Persists walkerOS events to SQLite, with one interface over two drivers:
10
+ better-sqlite3 for local files and @libsql/client for remote Turso / libSQL.
74
11
 
75
- ## Setup
12
+ [Documentation](https://www.walkeros.io/docs/destinations/server/sqlite) &bull;
13
+ [NPM Package](https://www.npmjs.com/package/@walkeros/server-destination-sqlite)
14
+ &bull;
15
+ [Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/sqlite)
76
16
 
77
- Create the events table and apply pragmas with one command:
17
+ ## Installation
78
18
 
79
19
  ```bash
80
- walkeros setup destination.sqlite
20
+ npm install @walkeros/server-destination-sqlite
81
21
  ```
82
22
 
83
- This runs `CREATE TABLE IF NOT EXISTS` with the canonical 15-column walkerOS
84
- Event v4 schema and applies four pragmas:
85
-
86
- - `journal_mode = WAL` (better concurrent reads)
87
- - `synchronous = NORMAL` (good durability vs. perf balance)
88
- - `foreign_keys = ON`
89
- - `temp_store = MEMORY`
90
-
91
- Setup is idempotent. Re-running against a populated database is a safe no-op.
92
- Drift between the declared schema and the actual table is logged as
93
- `WARN setup.drift {field, declared, actual}`. Setup never auto-mutates an
94
- existing table, no `ALTER TABLE`, no destructive recreates.
95
-
96
- The default 15-column schema mirrors the canonical walkerOS Event v4 layout.
97
- Only `name` is `NOT NULL`, every other column is nullable so partial events do
98
- not block ingestion:
99
-
100
- ```sql
101
- CREATE TABLE IF NOT EXISTS events (
102
- name TEXT NOT NULL,
103
- data TEXT,
104
- context TEXT,
105
- globals TEXT,
106
- custom TEXT,
107
- user TEXT,
108
- nested TEXT,
109
- consent TEXT,
110
- id TEXT,
111
- trigger TEXT,
112
- entity TEXT,
113
- action TEXT,
114
- timestamp TEXT,
115
- timing INTEGER,
116
- source TEXT
117
- )
118
- ```
119
-
120
- Override defaults in `config.setup`:
23
+ ## Quick start
121
24
 
122
25
  ```json
123
26
  {
124
- "destinations": {
125
- "sqlite": {
126
- "package": "@walkeros/server-destination-sqlite",
127
- "config": {
128
- "settings": { "sqlite": { "url": "./events.db" } },
129
- "setup": {
130
- "pragmas": { "journal_mode": "DELETE" },
131
- "indexes": [{ "name": "idx_events_name", "columns": ["name"] }]
27
+ "version": 4,
28
+ "flows": {
29
+ "default": {
30
+ "config": { "platform": "server" },
31
+ "destinations": {
32
+ "sqlite": {
33
+ "package": "@walkeros/server-destination-sqlite",
34
+ "config": {}
132
35
  }
133
36
  }
134
37
  }
@@ -136,53 +39,18 @@ Override defaults in `config.setup`:
136
39
  }
137
40
  ```
138
41
 
139
- `setup: true` accepts all defaults. `setup: false` (or omitted) means
140
- `walkeros setup destination.sqlite` is a no-op for this destination.
141
-
142
- ### Migration from `schema`
143
-
144
- The package-local `settings.sqlite.schema` setting is deprecated. The framework
145
- now owns the setup lifecycle through `config.setup`. The deprecated form still
146
- works and emits a one-time WARN through the destination logger.
147
-
148
- | Old (`settings.sqlite.schema`) | New (`config.setup`) | Effect |
149
- | ------------------------------ | -------------------- | -------------------------------------------------- |
150
- | `'auto'` | `true` | `walkeros setup destination.sqlite` creates table. |
151
- | `'manual'` | `false` | Setup is a no-op. Bring your own schema + mapping. |
152
- | omitted | omitted | No-op until `setup` is set explicitly. |
153
-
154
- Remove the `schema` field from `settings.sqlite` and add `setup: true` (or
155
- `false`) at the `config` level.
156
-
157
- ## Drivers
158
-
159
- - **Local** (`better-sqlite3`): sync native driver, ideal for single-host
160
- deployments. URL is treated as a filesystem path. `:memory:` works too. All
161
- four default pragmas are honored.
162
- - **Remote** (`@libsql/client`): async HTTP/WSS driver for Turso, sqld, or
163
- self-hosted libSQL. Auth via `authToken`. The remote server controls
164
- journaling, so client-side `journal_mode` is silently ignored. The other
165
- pragmas (`synchronous`, `foreign_keys`, `temp_store`) still apply.
166
-
167
- Both are peer dependencies. The destination picks the driver at `init()` time
168
- based on the URL prefix.
169
-
170
- ## Shutdown
171
-
172
- The destination calls `close()` on the connection during `destroy()`.
173
- User-provided clients (wired in via `env.client` or `settings.sqlite._client`)
174
- are not closed.
175
-
176
- ## Limitations
42
+ ## Documentation
177
43
 
178
- - v1 issues one `INSERT` per event. A `pushBatch` path is planned for v2.
179
- - Connection death is not auto-retried. A fatal driver error logs and drops
180
- events until the flow restarts.
44
+ Full configuration, mapping, and examples live in the docs:
45
+ **https://www.walkeros.io/docs/destinations/server/sqlite**
181
46
 
182
- ## Type Definitions
47
+ ## Contribute
183
48
 
184
- See [src/types/index.ts](./src/types/index.ts).
49
+ Feel free to contribute by submitting an
50
+ [issue](https://github.com/elbwalker/walkerOS/issues), starting a
51
+ [discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
52
+ [contact](https://calendly.com/elb-alexander/30min).
185
53
 
186
54
  ## License
187
55
 
188
- MIT.
56
+ MIT
package/dist/walkerOS.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$meta": {
3
3
  "package": "@walkeros/server-destination-sqlite",
4
- "version": "4.1.0-next-1778668930820",
4
+ "version": "4.1.0",
5
5
  "type": "destination",
6
6
  "platform": [
7
7
  "server"
@@ -54,7 +54,8 @@
54
54
  "url"
55
55
  ],
56
56
  "additionalProperties": false,
57
- "description": "SQLite / libSQL configuration (like { url: './events.db' } or { url: 'libsql://my-db.turso.io', authToken: '...' })"
57
+ "description": "SQLite / libSQL configuration (like { url: './events.db' } or { url: 'libsql://my-db.turso.io', authToken: '...' })",
58
+ "title": "sqlite"
58
59
  }
59
60
  },
60
61
  "required": [
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@walkeros/server-destination-sqlite",
3
3
  "description": "SQLite server destination for walkerOS (local via better-sqlite3, remote via libSQL/Turso)",
4
- "version": "4.1.0-next-1778668930820",
4
+ "version": "4.1.0",
5
5
  "license": "MIT",
6
6
  "main": "./dist/index.js",
7
7
  "module": "./dist/index.mjs",
@@ -25,7 +25,8 @@
25
25
  }
26
26
  },
27
27
  "files": [
28
- "dist/**"
28
+ "dist/**",
29
+ "CHANGELOG.md"
29
30
  ],
30
31
  "scripts": {
31
32
  "build": "tsup --silent",
@@ -37,8 +38,8 @@
37
38
  "update": "npx npm-check-updates -u && npm update"
38
39
  },
39
40
  "dependencies": {
40
- "@walkeros/core": "4.1.0-next-1778668930820",
41
- "@walkeros/server-core": "4.1.0-next-1778668930820"
41
+ "@walkeros/core": "4.1.0",
42
+ "@walkeros/server-core": "4.1.0"
42
43
  },
43
44
  "peerDependencies": {
44
45
  "better-sqlite3": "^11.0.0",
@@ -53,7 +54,7 @@
53
54
  }
54
55
  },
55
56
  "devDependencies": {
56
- "@walkeros/collector": "4.1.0-next-1778668930820",
57
+ "@walkeros/collector": "4.1.0",
57
58
  "better-sqlite3": "^11.0.0",
58
59
  "@libsql/client": "^0.14.0",
59
60
  "@types/better-sqlite3": "^7.6.11"