@xyo-network/xl1-driver-cloudflare-r2 4.0.12 → 4.0.15

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 (2) hide show
  1. package/README.md +62 -54
  2. package/package.json +13 -13
package/README.md CHANGED
@@ -5,29 +5,16 @@
5
5
  [![npm-badge][]][npm-link]
6
6
  [![license-badge][]][license-link]
7
7
 
8
- > Cloudflare R2-backed map driver for XL1 protocol storage — a persistent `AsyncIterableMap` over S3-compatible object storage.
8
+ > Cloudflare R2 and S3-compatible map driver for XL1 protocol storage.
9
9
 
10
- ## About
10
+ ## Description
11
11
 
12
- XL1 SDK components persist data through the `MapType` (`SyncMap | AsyncMap`) abstraction. This package provides `R2Map`, a Cloudflare R2-backed `AsyncIterableMap` that stores each entry as a JSON object keyed by the map key, with an optional in-memory `LruCacheMap` read-through cache, an optional key prefix so multiple maps can share one bucket, and paged `for await...of` iteration over all entries.
12
+ XL1 is the XYO Layer One blockchain protocol. This package provides `R2Map`, an
13
+ S3-compatible `AsyncIterableMap` for Cloudflare R2 buckets. It stores each value
14
+ as JSON under a deterministic object key and can optionally use an in-memory
15
+ read-through cache.
13
16
 
14
- R2 speaks the S3 API, so `R2Map` takes a configured [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3) `S3Client` pointed at your R2 endpoint:
15
-
16
- ```ts
17
- import { S3Client } from '@aws-sdk/client-s3'
18
- import { R2Map } from '@xyo-network/xl1-driver-cloudflare-r2'
19
-
20
- const client = new S3Client({
21
- region: 'auto',
22
- endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
23
- credentials: { accessKeyId, secretAccessKey },
24
- })
25
-
26
- const map = await R2Map.create({ bucket: 'summaries', client, prefix: 'blocks/' })
27
- await map.start()
28
- ```
29
-
30
- Because object storage has no per-value size ceiling comparable to document databases, `R2Map` suits large cached objects (e.g. block step summaries). Sibling drivers: [`@xyo-network/xl1-driver-memory`](https://www.npmjs.com/package/@xyo-network/xl1-driver-memory), [`@xyo-network/xl1-driver-lmdb`](https://www.npmjs.com/package/@xyo-network/xl1-driver-lmdb), [`@xyo-network/xl1-driver-mongodb`](https://www.npmjs.com/package/@xyo-network/xl1-driver-mongodb).
17
+ Use it for durable object-storage-backed maps in Node services and publishers.
31
18
 
32
19
  ## Install
33
20
 
@@ -55,50 +42,71 @@ Using bun:
55
42
  bun add @xyo-network/xl1-driver-cloudflare-r2
56
43
  ```
57
44
 
58
- > `@aws-sdk/client-s3` is an optional peer dependency — install it in the consuming application.
45
+ This package expects an `@aws-sdk/client-s3` `S3Client` configured for your R2
46
+ or S3-compatible endpoint.
59
47
 
60
- ## What's Inside
48
+ ## Usage
61
49
 
62
- - **`R2Map`** — an R2/S3-backed `AsyncIterableMap<K, V>`: async `get`/`set`/`has`/`getMany`/`setMany`/`delete`/`clear`, optional `LruCacheMap` read cache, key prefixing, and paged iteration over the whole map.
50
+ ```ts
51
+ import { S3Client } from '@aws-sdk/client-s3'
52
+ import { R2Map } from '@xyo-network/xl1-driver-cloudflare-r2'
63
53
 
64
- ## Building Locally
54
+ const client = new S3Client({
55
+ region: 'auto',
56
+ endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
57
+ credentials: { accessKeyId, secretAccessKey },
58
+ })
59
+
60
+ const map = await R2Map.create({
61
+ bucket: 'xl1-cache',
62
+ client,
63
+ prefix: 'blocks/',
64
+ getCache: { enabled: true },
65
+ })
66
+
67
+ await map.start()
68
+ await map.set('head', { block: 42 })
69
+ ```
70
+
71
+ ## Documentation
72
+
73
+ `R2Map` implements async `get`, `set`, `has`, `getMany`, `setMany`, `delete`,
74
+ `clear`, and `for await...of` iteration over the matching object prefix.
75
+
76
+ Use `@xyo-network/xl1-s3-publishers` when you need to publish the complete XL1
77
+ static REST layout rather than a generic map abstraction.
78
+
79
+ ## AI Agent Skills
80
+
81
+ Install the recommended XL1/XYO skills with [Skills.sh](https://skills.sh):
82
+
83
+ ```sh
84
+ npx skills add XYOracleNetwork/xyo-skills --all
85
+ ```
86
+
87
+ In XY toolchain repos, the equivalent convenience command is:
65
88
 
66
89
  ```sh
67
- xy build @xyo-network/xl1-driver-cloudflare-r2
68
- xy test @xyo-network/xl1-driver-cloudflare-r2
69
- xy lint @xyo-network/xl1-driver-cloudflare-r2
90
+ pnpm xy skills defaults
91
+ pnpm xy skills lint --fix
70
92
  ```
71
93
 
72
- ## Maintainers
73
-
74
- <table>
75
- <tr>
76
- <td align="center" valign="top" width="120">
77
- <a href="https://github.com/arietrouw">
78
- <img src="https://github.com/arietrouw.png" width="80" height="80" alt="Arie Trouw" /><br />
79
- <sub><b>Arie Trouw</b></sub>
80
- </a>
81
- <br />
82
- <a href="https://arietrouw.com">arietrouw.com</a>
83
- </td>
84
- <td align="center" valign="top" width="120">
85
- <a href="https://github.com/jonesmac">
86
- <img src="https://github.com/jonesmac.png" width="80" height="80" alt="Matt Jones" /><br />
87
- <sub><b>Matt Jones</b></sub>
88
- </a>
89
- </td>
90
- <td align="center" valign="top" width="120">
91
- <a href="https://github.com/JoelBCarter">
92
- <img src="https://github.com/JoelBCarter.png" width="80" height="80" alt="Joel Carter" /><br />
93
- <sub><b>Joel Carter</b></sub>
94
- </a>
95
- </td>
96
- </tr>
97
- </table>
94
+ For XL1 work, ask your agent to use `xyo-knowledge`, `xl1-knowledge`, and
95
+ `xl1-patterns`. These skills cover XYO primitives, XL1 chain and gateway APIs,
96
+ and application patterns for XL1 dApps.
97
+
98
+ ## Building Locally
99
+
100
+ ```sh
101
+ pnpm xy build @xyo-network/xl1-driver-cloudflare-r2
102
+ pnpm xy test @xyo-network/xl1-driver-cloudflare-r2
103
+ pnpm xy lint @xyo-network/xl1-driver-cloudflare-r2
104
+ ```
98
105
 
99
106
  ## License
100
107
 
101
- See the [LICENSE](./LICENSE) file (LGPL-3.0-only).
108
+ See the [LICENSE](./LICENSE) file for license rights and limitations
109
+ (LGPL-3.0-only).
102
110
 
103
111
  ## Credits
104
112
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "http://json.schemastore.org/package.json",
3
3
  "name": "@xyo-network/xl1-driver-cloudflare-r2",
4
- "version": "4.0.12",
4
+ "version": "4.0.15",
5
5
  "description": "XYO Layer One SDK Protocol Cloudflare R2 Driver",
6
6
  "homepage": "https://xylabs.com",
7
7
  "bugs": {
@@ -35,13 +35,15 @@
35
35
  "README.md"
36
36
  ],
37
37
  "dependencies": {
38
- "@aws-sdk/client-s3": "~3.1080.0",
39
- "@xyo-network/xl1-protocol": "~4.0.12",
40
- "@xyo-network/xl1-sdk": "~4.0.12"
38
+ "@aws-sdk/client-s3": "~3.1084.0",
39
+ "@xyo-network/xl1-protocol": "~4.0.15",
40
+ "@xyo-network/xl1-sdk": "~4.0.15"
41
41
  },
42
42
  "devDependencies": {
43
- "@ariestools/sdk": "~8.0.3",
44
- "@ariestools/threads": "~8.0.3",
43
+ "@ariestools/sdk": "~8.0.5",
44
+ "@ariestools/threads": "~8.0.5",
45
+ "@ariestools/toolchain": "~8.7.4",
46
+ "@ariestools/tsconfig": "~8.7.4",
45
47
  "@bitauth/libauth": "~3.0.0",
46
48
  "@metamask/json-rpc-engine": "~10.5.0",
47
49
  "@metamask/providers": "~22.1.1",
@@ -50,10 +52,8 @@
50
52
  "@opentelemetry/sdk-trace-base": "~2.9.0",
51
53
  "@scure/base": "~2.2.0",
52
54
  "@scure/bip39": "~2.2.0",
53
- "@xylabs/toolchain": "~8.6.10",
54
- "@xylabs/tsconfig": "~8.6.10",
55
55
  "@xyo-network/sdk": "~7.0.11",
56
- "@xyo-network/sdk-protocol": "~7.0.15",
56
+ "@xyo-network/sdk-protocol": "~7.0.16",
57
57
  "ajv": "~8.20.0",
58
58
  "async-mutex": "~0.5.0",
59
59
  "debug": "~4.4.3",
@@ -64,14 +64,14 @@
64
64
  "observable-fns": "~0.6.1",
65
65
  "tslib": "~2.8.1",
66
66
  "typescript": "~6.0.3",
67
- "vite": "~8.1.3",
67
+ "vite": "~8.1.4",
68
68
  "vitest": "~4.1.10",
69
69
  "webextension-polyfill": "~0.12.0",
70
70
  "zod": "~4.4.3"
71
71
  },
72
72
  "peerDependencies": {
73
- "@ariestools/sdk": "^8.0.3",
74
- "@ariestools/threads": "^8.0.3",
73
+ "@ariestools/sdk": "^8.0.5",
74
+ "@ariestools/threads": "^8.0.5",
75
75
  "@bitauth/libauth": "^3.0.0",
76
76
  "@metamask/json-rpc-engine": "^10.5.0",
77
77
  "@metamask/providers": "^22.1.1",
@@ -81,7 +81,7 @@
81
81
  "@scure/base": "^2.2.0",
82
82
  "@scure/bip39": "^2.2.0",
83
83
  "@xyo-network/sdk": "^7.0.11",
84
- "@xyo-network/sdk-protocol": "^7.0.15",
84
+ "@xyo-network/sdk-protocol": "^7.0.16",
85
85
  "ajv": "^8.20.0",
86
86
  "async-mutex": "^0.5.0",
87
87
  "debug": "^4.4.3",