@xyo-network/xl1-driver-cloudflare-r2 2.0.12

package/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,111 @@
+[![logo][]](https://xyo.network)
+
+# @xyo-network/xl1-driver-cloudflare-r2
+
+[![npm-badge][]][npm-link]
+[![license-badge][]][license-link]
+
+> Cloudflare R2-backed map driver for XL1 protocol storage — a persistent `AsyncIterableMap` over S3-compatible object storage.
+
+## About
+
+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.
+
+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:
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3'
+import { R2Map } from '@xyo-network/xl1-driver-cloudflare-r2'
+
+const client = new S3Client({
+  region: 'auto',
+  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+  credentials: { accessKeyId, secretAccessKey },
+})
+
+const map = await R2Map.create({ bucket: 'summaries', client, prefix: 'blocks/' })
+await map.start()
+```
+
+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).
+
+## Install
+
+Using npm:
+
+```sh
+npm i --save @xyo-network/xl1-driver-cloudflare-r2
+```
+
+Using yarn:
+
+```sh
+yarn add @xyo-network/xl1-driver-cloudflare-r2
+```
+
+Using pnpm:
+
+```sh
+pnpm add @xyo-network/xl1-driver-cloudflare-r2
+```
+
+Using bun:
+
+```sh
+bun add @xyo-network/xl1-driver-cloudflare-r2
+```
+
+> `@aws-sdk/client-s3` is an optional peer dependency — install it in the consuming application.
+
+## What's Inside
+
+- **`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.
+
+## Building Locally
+
+```sh
+xy build @xyo-network/xl1-driver-cloudflare-r2
+xy test @xyo-network/xl1-driver-cloudflare-r2
+xy lint @xyo-network/xl1-driver-cloudflare-r2
+```
+
+## Maintainers
+
+<table>
+  <tr>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/arietrouw">
+        <img src="https://github.com/arietrouw.png" width="80" height="80" alt="Arie Trouw" /><br />
+        <sub><b>Arie Trouw</b></sub>
+      </a>
+      <br />
+      <a href="https://arietrouw.com">arietrouw.com</a>
+    </td>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/jonesmac">
+        <img src="https://github.com/jonesmac.png" width="80" height="80" alt="Matt Jones" /><br />
+        <sub><b>Matt Jones</b></sub>
+      </a>
+    </td>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/JoelBCarter">
+        <img src="https://github.com/JoelBCarter.png" width="80" height="80" alt="Joel Carter" /><br />
+        <sub><b>Joel Carter</b></sub>
+      </a>
+    </td>
+  </tr>
+</table>
+
+## License
+
+See the [LICENSE](./LICENSE) file (LGPL-3.0-only).
+
+## Credits
+
+[Made with 🔥 and ❄️ by XYO Foundation](https://xyo.network)
+
+[npm-badge]: https://img.shields.io/npm/v/@xyo-network/xl1-driver-cloudflare-r2.svg
+[npm-link]: https://www.npmjs.com/package/@xyo-network/xl1-driver-cloudflare-r2
+[license-badge]: https://img.shields.io/npm/l/@xyo-network/xl1-driver-cloudflare-r2.svg
+[license-link]: ./LICENSE
+[logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png

package/dist/neutral/R2Map.d.ts

@@ -0,0 +1,39 @@
+import type { S3Client } from '@aws-sdk/client-s3';
+import type { CreatableParams } from '@xylabs/sdk-js';
+import { AbstractCreatable } from '@xylabs/sdk-js';
+import type { AsyncIterableMap } from '@xyo-network/xl1-protocol-lib';
+export interface R2MapParams extends CreatableParams {
+    bucket: string;
+    /**
+     * S3-compatible client pointed at the Cloudflare R2 endpoint
+     * (`https://<account-id>.r2.cloudflarestorage.com`).
+     */
+    client: S3Client;
+    getCache?: {
+        enabled: boolean;
+        maxEntries?: number;
+    };
+    /** Optional key prefix, allowing multiple maps to share one bucket. */
+    prefix?: string;
+}
+export declare class R2Map<K extends string = string, V extends {} = {}> extends AbstractCreatable<R2MapParams> implements AsyncIterableMap<K, V> {
+    private _getCache;
+    get bucket(): string;
+    get client(): S3Client;
+    get prefix(): string;
+    /**
+     * Enable `for await...of` iteration over all entries in the map.
+     * Pages through ListObjectsV2 so no fixed result limit is applied.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<[K, V]>;
+    clear(): Promise<void>;
+    delete(id: K): Promise<boolean>;
+    get(id: K): Promise<V | undefined>;
+    getMany(ids: K[]): Promise<V[]>;
+    has(id: K): Promise<boolean>;
+    set(id: K, data: V): Promise<void>;
+    setMany(entries: [K, V][]): Promise<void>;
+    startHandler(): Promise<void>;
+    private objectKey;
+}
+//# sourceMappingURL=R2Map.d.ts.map

package/dist/neutral/R2Map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"R2Map.d.ts","sourceRoot":"","sources":["../../src/R2Map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAIlD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EACL,iBAAiB,EAClB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,KAAK,EAAE,gBAAgB,EAAW,MAAM,+BAA+B,CAAA;AAE9E,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,MAAM,EAAE,QAAQ,CAAA;IAChB,QAAQ,CAAC,EAAE;QACT,OAAO,EAAE,OAAO,CAAA;QAChB,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,CAAA;IACD,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAQD,qBACa,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAC7D,SAAQ,iBAAiB,CAAC,WAAW,CACrC,YAAW,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC;IACjC,OAAO,CAAC,SAAS,CAA2B;IAE5C,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,MAAM,IAAI,QAAQ,CAErB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;OAGG;IACH,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IA0CzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/B,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAoBlC,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAK/B,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAc5B,GAAG,CAAC,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5C,OAAO,CAAC,SAAS;CAGlB"}

package/dist/neutral/index.d.ts

@@ -0,0 +1,2 @@
+export * from './R2Map.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/neutral/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/dist/neutral/index.mjs

@@ -0,0 +1,169 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/R2Map.ts
+import {
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand
+} from "@aws-sdk/client-s3";
+import {
+  AbstractCreatable,
+  assertEx,
+  creatable,
+  isDefined
+} from "@xylabs/sdk-js";
+import { LruCacheMap } from "@xyo-network/xl1-driver-memory";
+var isNotFoundError = (error) => {
+  if (typeof error !== "object" || error === null) return false;
+  const { name, $metadata } = error;
+  return name === "NoSuchKey" || name === "NotFound" || $metadata?.httpStatusCode === 404;
+};
+var R2Map = class extends AbstractCreatable {
+  _getCache;
+  get bucket() {
+    return assertEx(this.params.bucket, () => "No bucket specified");
+  }
+  get client() {
+    return assertEx(this.params.client, () => "No client specified");
+  }
+  get prefix() {
+    return this.params.prefix ?? "";
+  }
+  /**
+   * Enable `for await...of` iteration over all entries in the map.
+   * Pages through ListObjectsV2 so no fixed result limit is applied.
+   */
+  [Symbol.asyncIterator]() {
+    let pageKeys = [];
+    let continuationToken;
+    let exhausted = false;
+    const loadNextPage = async () => {
+      const response = await this.client.send(new ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: this.prefix === "" ? void 0 : this.prefix,
+        ContinuationToken: continuationToken
+      }));
+      pageKeys = (response.Contents ?? []).map((object) => object.Key).filter(isDefined).map((key) => key.slice(this.prefix.length));
+      continuationToken = response.NextContinuationToken;
+      exhausted = continuationToken === void 0;
+    };
+    return {
+      next: async () => {
+        for (; ; ) {
+          while (pageKeys.length === 0) {
+            if (exhausted) return { value: void 0, done: true };
+            await loadNextPage();
+          }
+          const key = pageKeys.shift();
+          const value = await this.get(key);
+          if (value === void 0) continue;
+          return { value: [key, value], done: false };
+        }
+      }
+    };
+  }
+  async clear() {
+    await this._getCache?.clear();
+    let continuationToken;
+    do {
+      const response = await this.client.send(new ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: this.prefix === "" ? void 0 : this.prefix,
+        ContinuationToken: continuationToken
+      }));
+      const keys = (response.Contents ?? []).map((object) => object.Key).filter(isDefined);
+      if (keys.length > 0) {
+        await this.client.send(new DeleteObjectsCommand({
+          Bucket: this.bucket,
+          Delete: { Objects: keys.map((key) => ({ Key: key })) }
+        }));
+      }
+      continuationToken = response.NextContinuationToken;
+    } while (continuationToken !== void 0);
+  }
+  async delete(id) {
+    await this._getCache?.delete(id);
+    const existed = await this.has(id);
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: this.objectKey(id) }));
+    return existed;
+  }
+  async get(id) {
+    if (this._getCache) {
+      const getCacheResult = await this._getCache.get(id);
+      if (getCacheResult) {
+        return getCacheResult;
+      }
+    }
+    try {
+      const response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: this.objectKey(id) }));
+      const body = await response.Body?.transformToString();
+      if (body === void 0) return void 0;
+      const value = JSON.parse(body);
+      await this._getCache?.set(id, value);
+      return value;
+    } catch (error) {
+      if (isNotFoundError(error)) return void 0;
+      throw error;
+    }
+  }
+  async getMany(ids) {
+    const results = await Promise.all(ids.map((id) => this.get(id)));
+    return results.filter(isDefined);
+  }
+  async has(id) {
+    if (this._getCache) {
+      const getCacheResult = await this._getCache.has(id);
+      if (getCacheResult) return getCacheResult;
+    }
+    try {
+      await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: this.objectKey(id) }));
+      return true;
+    } catch (error) {
+      if (isNotFoundError(error)) return false;
+      throw error;
+    }
+  }
+  async set(id, data) {
+    await this.client.send(new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: this.objectKey(id),
+      Body: JSON.stringify(data),
+      ContentType: "application/json"
+    }));
+    await this._getCache?.set(id, data);
+  }
+  async setMany(entries) {
+    for (const [key, value] of entries) {
+      await this.set(key, value);
+    }
+  }
+  async startHandler() {
+    await super.startHandler();
+    if (this.params.getCache?.enabled === true) {
+      const maxEntries = this.params.getCache?.maxEntries ?? 5e3;
+      this._getCache = new LruCacheMap({ max: maxEntries });
+    }
+  }
+  objectKey(id) {
+    return `${this.prefix}${id}`;
+  }
+};
+R2Map = __decorateClass([
+  creatable()
+], R2Map);
+export {
+  R2Map
+};
+//# sourceMappingURL=index.mjs.map

package/dist/neutral/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/R2Map.ts"],
+  "sourcesContent": ["import type { S3Client } from '@aws-sdk/client-s3'\nimport {\n  DeleteObjectCommand, DeleteObjectsCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand,\n} from '@aws-sdk/client-s3'\nimport type { CreatableParams } from '@xylabs/sdk-js'\nimport {\n  AbstractCreatable, assertEx, creatable, isDefined,\n} from '@xylabs/sdk-js'\nimport { LruCacheMap } from '@xyo-network/xl1-driver-memory'\nimport type { AsyncIterableMap, MapType } from '@xyo-network/xl1-protocol-lib'\n\nexport interface R2MapParams extends CreatableParams {\n  bucket: string\n  /**\n   * S3-compatible client pointed at the Cloudflare R2 endpoint\n   * (`https://<account-id>.r2.cloudflarestorage.com`).\n   */\n  client: S3Client\n  getCache?: {\n    enabled: boolean\n    maxEntries?: number\n  }\n  /** Optional key prefix, allowing multiple maps to share one bucket. */\n  prefix?: string\n}\n\nconst isNotFoundError = (error: unknown): boolean => {\n  if (typeof error !== 'object' || error === null) return false\n  const { name, $metadata } = error as { $metadata?: { httpStatusCode?: number }; name?: string }\n  return name === 'NoSuchKey' || name === 'NotFound' || $metadata?.httpStatusCode === 404\n}\n\n@creatable()\nexport class R2Map<K extends string = string, V extends {} = {}>\n  extends AbstractCreatable<R2MapParams>\n  implements AsyncIterableMap<K, V> {\n  private _getCache: MapType<K, V> | undefined\n\n  get bucket(): string {\n    return assertEx(this.params.bucket, () => 'No bucket specified')\n  }\n\n  get client(): S3Client {\n    return assertEx(this.params.client, () => 'No client specified')\n  }\n\n  get prefix(): string {\n    return this.params.prefix ?? ''\n  }\n\n  /**\n   * Enable `for await...of` iteration over all entries in the map.\n   * Pages through ListObjectsV2 so no fixed result limit is applied.\n   */\n  [Symbol.asyncIterator](): AsyncIterator<[K, V]> {\n    // Keys from the current page, drained front-to-back as the iterator advances.\n    let pageKeys: K[] = []\n    // Continuation token for the next page; undefined once the final page is consumed.\n    let continuationToken: string | undefined\n    let exhausted = false\n\n    const loadNextPage = async (): Promise<void> => {\n      const response = await this.client.send(new ListObjectsV2Command({\n        Bucket: this.bucket,\n        Prefix: this.prefix === '' ? undefined : this.prefix,\n        ContinuationToken: continuationToken,\n      }))\n      pageKeys = (response.Contents ?? [])\n        .map(object => object.Key)\n        .filter(isDefined)\n        .map(key => key.slice(this.prefix.length) as K)\n      continuationToken = response.NextContinuationToken\n      exhausted = continuationToken === undefined\n    }\n\n    return {\n      next: async (): Promise<IteratorResult<[K, V]>> => {\n        for (;;) {\n          // Refill from the next page whenever the current one is drained.\n          while (pageKeys.length === 0) {\n            if (exhausted) return { value: undefined, done: true }\n            await loadNextPage()\n          }\n\n          const key = pageKeys.shift()!\n          const value = await this.get(key)\n          // The object may have been deleted between listing and reading; skip it.\n          if (value === undefined) continue\n\n          // Yield the entry to the async iterator consumer (get() already populated the cache).\n          return { value: [key, value], done: false }\n        }\n      },\n    }\n  }\n\n  async clear(): Promise<void> {\n    await this._getCache?.clear()\n    // DeleteObjects accepts at most 1000 keys per request; page through the bucket until empty.\n    let continuationToken: string | undefined\n    do {\n      const response = await this.client.send(new ListObjectsV2Command({\n        Bucket: this.bucket,\n        Prefix: this.prefix === '' ? undefined : this.prefix,\n        ContinuationToken: continuationToken,\n      }))\n      const keys = (response.Contents ?? []).map(object => object.Key).filter(isDefined)\n      if (keys.length > 0) {\n        await this.client.send(new DeleteObjectsCommand({\n          Bucket: this.bucket,\n          Delete: { Objects: keys.map(key => ({ Key: key })) },\n        }))\n      }\n      continuationToken = response.NextContinuationToken\n    } while (continuationToken !== undefined)\n  }\n\n  async delete(id: K): Promise<boolean> {\n    await this._getCache?.delete(id)\n\n    // S3-style deletes are idempotent and do not report prior existence, so check first.\n    const existed = await this.has(id)\n    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: this.objectKey(id) }))\n    return existed\n  }\n\n  async get(id: K): Promise<V | undefined> {\n    if (this._getCache) {\n      const getCacheResult = await this._getCache.get(id)\n      if (getCacheResult) {\n        return getCacheResult\n      }\n    }\n    try {\n      const response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: this.objectKey(id) }))\n      const body = await response.Body?.transformToString()\n      if (body === undefined) return undefined\n      const value = JSON.parse(body) as V\n      await this._getCache?.set(id, value)\n      return value\n    } catch (error) {\n      if (isNotFoundError(error)) return undefined\n      throw error\n    }\n  }\n\n  async getMany(ids: K[]): Promise<V[]> {\n    const results = await Promise.all(ids.map(id => this.get(id)))\n    return results.filter(isDefined)\n  }\n\n  async has(id: K): Promise<boolean> {\n    if (this._getCache) {\n      const getCacheResult = await this._getCache.has(id)\n      if (getCacheResult) return getCacheResult\n    }\n    try {\n      await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: this.objectKey(id) }))\n      return true\n    } catch (error) {\n      if (isNotFoundError(error)) return false\n      throw error\n    }\n  }\n\n  async set(id: K, data: V): Promise<void> {\n    await this.client.send(new PutObjectCommand({\n      Bucket: this.bucket,\n      Key: this.objectKey(id),\n      Body: JSON.stringify(data),\n      ContentType: 'application/json',\n    }))\n    await this._getCache?.set(id, data)\n  }\n\n  async setMany(entries: [K, V][]): Promise<void> {\n    // TODO: Optimize with bounded concurrency\n    for (const [key, value] of entries) {\n      await this.set(key, value)\n    }\n  }\n\n  override async startHandler(): Promise<void> {\n    await super.startHandler()\n    if (this.params.getCache?.enabled === true) {\n      const maxEntries = this.params.getCache?.maxEntries ?? 5000\n      this._getCache = new LruCacheMap<K, V>({ max: maxEntries })\n    }\n  }\n\n  private objectKey(id: K): string {\n    return `${this.prefix}${id}`\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json.schemastore.org/package.json",
+  "name": "@xyo-network/xl1-driver-cloudflare-r2",
+  "version": "2.0.12",
+  "description": "XYO Layer One SDK Protocol Cloudflare R2 Driver",
+  "homepage": "https://xylabs.com",
+  "bugs": {
+    "url": "https://github.com/XYOracleNetwork/xl1-protocol/issues",
+    "email": "support@xylabs.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XYOracleNetwork/xl1-protocol.git"
+  },
+  "license": "LGPL-3.0-only",
+  "author": {
+    "name": "XY Labs Development Team",
+    "email": "support@xylabs.com",
+    "url": "https://xylabs.com"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/neutral/index.d.ts",
+      "default": "./dist/neutral/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!**/*.bench.*",
+    "!**/*.spec.*",
+    "!**/*.test.*",
+    "README.md"
+  ],
+  "dependencies": {
+    "@xyo-network/xl1-protocol-lib": "~2.0.12",
+    "@xyo-network/xl1-driver-memory": "~2.0.12"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@bitauth/libauth": "~3.0",
+    "@metamask/providers": "^22.1",
+    "@noble/post-quantum": "~0.6.1",
+    "@opentelemetry/api": "^1.9",
+    "@opentelemetry/sdk-trace-base": "^2.7",
+    "@scure/base": "~2.2",
+    "@scure/bip39": "~2.2",
+    "@xylabs/geo": "^6.0",
+    "@xylabs/sdk-js": "^6.0.10",
+    "@xylabs/threads": "~6.0",
+    "@xylabs/toolchain": "~8.1.19",
+    "@xylabs/tsconfig": "~8.1.19",
+    "@xyo-network/address": "^6.0",
+    "@xyo-network/sdk-js": "^6.0",
+    "@xyo-network/sdk-protocol-js": "~6.0",
+    "ajv": "^8.20",
+    "async-mutex": "^0.5",
+    "bn.js": "^5.2",
+    "buffer": "^6.0",
+    "debug": "~4.4",
+    "eslint": "^10.4.1",
+    "ethers": "^6.16",
+    "hash-wasm": "~4.12",
+    "idb": "^8.0",
+    "lru-cache": "^11.3",
+    "observable-fns": "~0.6",
+    "typescript": "~6.0.3",
+    "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
+    "vitest": "~4.1.8",
+    "webextension-polyfill": "^0.12",
+    "zod": "~4.4"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.700",
+    "@bitauth/libauth": "~3.0",
+    "@metamask/providers": "^22.1",
+    "@noble/post-quantum": "~0.6.1",
+    "@opentelemetry/api": "^1.9",
+    "@opentelemetry/sdk-trace-base": "^2.7",
+    "@scure/base": "~2.2",
+    "@scure/bip39": "~2.2",
+    "@xylabs/geo": "^6.0",
+    "@xylabs/sdk-js": "^6.0",
+    "@xylabs/threads": "~6.0",
+    "@xyo-network/address": "^6.0",
+    "@xyo-network/sdk-js": "^6.0",
+    "@xyo-network/sdk-protocol-js": "~6.0",
+    "ajv": "^8.20",
+    "async-mutex": "^0.5",
+    "bn.js": "^5.2",
+    "buffer": "^6.0",
+    "debug": "~4.4",
+    "ethers": "^6.16",
+    "hash-wasm": "~4.12",
+    "idb": "^8.0",
+    "lru-cache": "^11.3",
+    "observable-fns": "~0.6",
+    "webextension-polyfill": "^0.12",
+    "zod": "~4.4"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.3"
+  },
+  "engineStrict": true,
+  "publishConfig": {
+    "access": "public"
+  }
+}