@rljson/bs 0.0.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rljson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.architecture.md

@@ -0,0 +1,9 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Architecture

package/README.blog.md

@@ -0,0 +1,11 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Blog
+
+Add latest posts at the end.

package/README.contributors.md

@@ -0,0 +1,32 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Contributors Guide
+
+- [Prepare](#prepare)
+- [Develop](#develop)
+- [Administrate](#administrate)
+- [Fast Coding](#fast-coding)
+
+## Prepare
+
+Read [prepare.md](doc/prepare.md)
+
+<!-- ........................................................................-->
+
+## Develop
+
+Read [develop.md](doc/develop.md)
+
+## Administrate
+
+Read [create-new-repo.md](doc/create-new-repo.md)
+
+## Fast Coding
+
+Read [fast-coding-guide.md](doc/fast-coding-guide.md)

package/README.md

@@ -0,0 +1,24 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/bs
+
+## Users
+
+| File                                 | Purpose                     |
+| ------------------------------------ | --------------------------- |
+| [README.public.md](README.public.md) | Install and use the package |
+
+## Contributors
+
+| File                                             | Purpose                       |
+| ------------------------------------------------ | ----------------------------- |
+| [README.contributors.md](README.contributors.md) | Run, debug, build and publish |
+| [README.architecture.md](README.architecture.md) | Software architecture guide   |
+| [README.trouble.md](README.trouble.md)           | Errors & solutions            |
+| [README.blog.md](README.blog.md)                 | Blog                          |

package/README.public.md

@@ -0,0 +1,15 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/bs
+
+Blob storage interface and implementations for rljson.
+
+## Example
+
+[src/example.ts](src/example.ts)

package/README.trouble.md

@@ -0,0 +1,23 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Trouble shooting
+
+## Table of contents <!-- omit in toc -->
+
+- [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
+
+## Vscode Windows: Debugging is not working
+
+Date: 2025-03-08
+
+⚠️ IMPORTANT: On Windows, please check out the repo on drive C. There is a bug
+in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
+working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
+time to time if the issue has been fixed and remove this note once it is
+resolved.

package/dist/README.architecture.md

@@ -0,0 +1,9 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Architecture

package/dist/README.blog.md

@@ -0,0 +1,11 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Blog
+
+Add latest posts at the end.

package/dist/README.contributors.md

@@ -0,0 +1,32 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Contributors Guide
+
+- [Prepare](#prepare)
+- [Develop](#develop)
+- [Administrate](#administrate)
+- [Fast Coding](#fast-coding)
+
+## Prepare
+
+Read [prepare.md](doc/prepare.md)
+
+<!-- ........................................................................-->
+
+## Develop
+
+Read [develop.md](doc/develop.md)
+
+## Administrate
+
+Read [create-new-repo.md](doc/create-new-repo.md)
+
+## Fast Coding
+
+Read [fast-coding-guide.md](doc/fast-coding-guide.md)

package/dist/README.md

@@ -0,0 +1,24 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/bs
+
+## Users
+
+| File                                 | Purpose                     |
+| ------------------------------------ | --------------------------- |
+| [README.public.md](README.public.md) | Install and use the package |
+
+## Contributors
+
+| File                                             | Purpose                       |
+| ------------------------------------------------ | ----------------------------- |
+| [README.contributors.md](README.contributors.md) | Run, debug, build and publish |
+| [README.architecture.md](README.architecture.md) | Software architecture guide   |
+| [README.trouble.md](README.trouble.md)           | Errors & solutions            |
+| [README.blog.md](README.blog.md)                 | Blog                          |

package/dist/README.public.md

@@ -0,0 +1,15 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/bs
+
+Blob storage interface and implementations for rljson.
+
+## Example
+
+[src/example.ts](src/example.ts)

package/dist/README.trouble.md

@@ -0,0 +1,23 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Trouble shooting
+
+## Table of contents <!-- omit in toc -->
+
+- [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
+
+## Vscode Windows: Debugging is not working
+
+Date: 2025-03-08
+
+⚠️ IMPORTANT: On Windows, please check out the repo on drive C. There is a bug
+in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
+working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
+time to time if the issue has been fixed and remove this note once it is
+resolved.

package/dist/bs-mem.d.ts

@@ -0,0 +1,33 @@
+import { BlobProperties, Bs, DownloadBlobOptions, ListBlobsOptions, ListBlobsResult } from './bs.js';
+/**
+ * In-memory implementation of content-addressable blob storage.
+ * All blobs are stored in memory using a Map.
+ * Useful for testing and development.
+ */
+export declare class BsMem implements Bs {
+    private readonly blobs;
+    /**
+     * Convert content to Buffer
+     * @param content - Content to convert (Buffer, string, or ReadableStream)
+     */
+    private toBuffer;
+    setBlob(content: Buffer | string | ReadableStream): Promise<BlobProperties>;
+    getBlob(blobId: string, options?: DownloadBlobOptions): Promise<{
+        content: Buffer;
+        properties: BlobProperties;
+    }>;
+    getBlobStream(blobId: string): Promise<ReadableStream>;
+    deleteBlob(blobId: string): Promise<void>;
+    blobExists(blobId: string): Promise<boolean>;
+    getBlobProperties(blobId: string): Promise<BlobProperties>;
+    listBlobs(options?: ListBlobsOptions): Promise<ListBlobsResult>;
+    generateSignedUrl(blobId: string, expiresIn: number, permissions?: 'read' | 'delete'): Promise<string>;
+    /**
+     * Clear all blobs from storage (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get the number of blobs in storage
+     */
+    get size(): number;
+}

package/dist/bs-test-setup.d.ts

@@ -0,0 +1,25 @@
+import { Bs } from './bs.js';
+/**
+ * Bs implementation need to implement this interface to be used in
+ * conformance tests.
+ */
+export interface BsTestSetup {
+    /** Setup before all tests */
+    beforeAll: () => Promise<void>;
+    /**
+     * Initializes the Bs implementation.
+     * Should create a fresh instance for each test.
+     */
+    beforeEach: () => Promise<void>;
+    /**
+     * Tears down the Bs implementation.
+     * Should clean up resources after each test.
+     */
+    afterEach: () => Promise<void>;
+    /** Cleanup after all tests */
+    afterAll: () => Promise<void>;
+    /**
+     * The Bs implementation to be used in the conformance tests.
+     */
+    bs: Bs;
+}

package/dist/bs.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Content-addressable blob storage interface.
+ * Blobs are identified by SHA256 hash of their content.
+ * Uses a flat storage pool - all blobs are stored globally by their content hash.
+ * Metadata and organizational grouping is managed externally.
+ */
+/**
+ * Properties of a blob (minimal, as metadata is external)
+ */
+export interface BlobProperties {
+    /** SHA256 hash of the blob content (unique identifier) */
+    blobId: string;
+    /** Size in bytes */
+    size: number;
+    /** When the blob was first stored */
+    createdAt: Date;
+}
+/**
+ * Options for downloading a blob
+ */
+export interface DownloadBlobOptions {
+    /** Download only a byte range (e.g., for resumable downloads) */
+    range?: {
+        start: number;
+        end?: number;
+    };
+}
+/**
+ * Options for listing blobs
+ */
+export interface ListBlobsOptions {
+    /** Filter by ID prefix */
+    prefix?: string;
+    /** Maximum number of results */
+    maxResults?: number;
+    /** Continuation token for pagination */
+    continuationToken?: string;
+}
+/**
+ * Result of listing blobs
+ */
+export interface ListBlobsResult {
+    /** Array of blob properties */
+    blobs: BlobProperties[];
+    /** Token for fetching next page */
+    continuationToken?: string;
+}
+/**
+ * Content-Addressable Blob Storage Interface
+ * Flat storage pool - no containers/buckets needed
+ */
+export interface Bs {
+    /**
+     * Store a blob. The blob ID (SHA256 hash) is calculated from content.
+     * If a blob with the same content already exists, it returns existing blob properties.
+     * @param content - Blob content (Buffer, string, or stream)
+     * @returns Properties of the stored blob (including calculated blobId)
+     */
+    setBlob(content: Buffer | string | ReadableStream): Promise<BlobProperties>;
+    /**
+     * Get a blob from storage by its ID
+     * @param blobId - SHA256 hash of the blob
+     * @param options - Download options
+     * @returns Blob content and properties
+     */
+    getBlob(blobId: string, options?: DownloadBlobOptions): Promise<{
+        content: Buffer;
+        properties: BlobProperties;
+    }>;
+    /**
+     * Get a readable stream for a blob
+     * @param blobId - SHA256 hash of the blob
+     * @returns Readable stream
+     */
+    getBlobStream(blobId: string): Promise<ReadableStream>;
+    /**
+     * Delete a blob by its ID
+     * Note: In a production system, consider reference counting before deletion
+     * @param blobId - SHA256 hash of the blob
+     */
+    deleteBlob(blobId: string): Promise<void>;
+    /**
+     * Check if a blob exists
+     * @param blobId - SHA256 hash of the blob
+     * @returns True if exists
+     */
+    blobExists(blobId: string): Promise<boolean>;
+    /**
+     * Get blob properties without downloading content
+     * @param blobId - SHA256 hash of the blob
+     * @returns Blob properties
+     */
+    getBlobProperties(blobId: string): Promise<BlobProperties>;
+    /**
+     * List all blobs in the storage pool
+     * @param options - List options
+     * @returns List of blobs with optional continuation token
+     */
+    listBlobs(options?: ListBlobsOptions): Promise<ListBlobsResult>;
+    /**
+     * Get a signed URL for temporary access to a blob
+     * @param blobId - SHA256 hash of the blob
+     * @param expiresIn - Expiration time in seconds
+     * @param permissions - Permissions ('read' or 'delete')
+     * @returns Signed URL
+     */
+    generateSignedUrl(blobId: string, expiresIn: number, permissions?: 'read' | 'delete'): Promise<string>;
+}

package/dist/bs.js

@@ -0,0 +1,129 @@
+import { hshBuffer } from "@rljson/hash";
+import { Readable } from "node:stream";
+class BsMem {
+  blobs = /* @__PURE__ */ new Map();
+  /**
+   * Convert content to Buffer
+   * @param content - Content to convert (Buffer, string, or ReadableStream)
+   */
+  async toBuffer(content) {
+    if (Buffer.isBuffer(content)) {
+      return content;
+    }
+    if (typeof content === "string") {
+      return Buffer.from(content, "utf8");
+    }
+    const reader = content.getReader();
+    const chunks = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+  }
+  async setBlob(content) {
+    const buffer = await this.toBuffer(content);
+    const blobId = hshBuffer(buffer);
+    const existing = this.blobs.get(blobId);
+    if (existing) {
+      return existing.properties;
+    }
+    const properties = {
+      blobId,
+      size: buffer.length,
+      createdAt: /* @__PURE__ */ new Date()
+    };
+    this.blobs.set(blobId, {
+      content: buffer,
+      properties
+    });
+    return properties;
+  }
+  async getBlob(blobId, options) {
+    const stored = this.blobs.get(blobId);
+    if (!stored) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+    let content = stored.content;
+    if (options?.range) {
+      const { start, end } = options.range;
+      content = stored.content.subarray(start, end);
+    }
+    return {
+      content,
+      properties: stored.properties
+    };
+  }
+  async getBlobStream(blobId) {
+    const stored = this.blobs.get(blobId);
+    if (!stored) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+    const nodeStream = Readable.from(stored.content);
+    return Readable.toWeb(nodeStream);
+  }
+  async deleteBlob(blobId) {
+    const deleted = this.blobs.delete(blobId);
+    if (!deleted) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+  }
+  async blobExists(blobId) {
+    return this.blobs.has(blobId);
+  }
+  async getBlobProperties(blobId) {
+    const stored = this.blobs.get(blobId);
+    if (!stored) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+    return stored.properties;
+  }
+  async listBlobs(options) {
+    let blobs = Array.from(this.blobs.values()).map(
+      (stored) => stored.properties
+    );
+    if (options?.prefix) {
+      blobs = blobs.filter((blob) => blob.blobId.startsWith(options.prefix));
+    }
+    blobs.sort((a, b) => a.blobId.localeCompare(b.blobId));
+    const maxResults = options?.maxResults ?? blobs.length;
+    let startIndex = 0;
+    if (options?.continuationToken) {
+      const tokenIndex = blobs.findIndex(
+        (blob) => blob.blobId === options.continuationToken
+      );
+      startIndex = tokenIndex === -1 ? 0 : tokenIndex + 1;
+    }
+    const endIndex = Math.min(startIndex + maxResults, blobs.length);
+    const pageBlobs = blobs.slice(startIndex, endIndex);
+    const continuationToken = endIndex < blobs.length ? pageBlobs[pageBlobs.length - 1]?.blobId : void 0;
+    return {
+      blobs: pageBlobs,
+      continuationToken
+    };
+  }
+  async generateSignedUrl(blobId, expiresIn, permissions) {
+    if (!this.blobs.has(blobId)) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+    const expires = Date.now() + expiresIn * 1e3;
+    const perm = permissions ?? "read";
+    return `mem://${blobId}?expires=${expires}&permissions=${perm}`;
+  }
+  /**
+   * Clear all blobs from storage (useful for testing)
+   */
+  clear() {
+    this.blobs.clear();
+  }
+  /**
+   * Get the number of blobs in storage
+   */
+  get size() {
+    return this.blobs.size;
+  }
+}
+export {
+  BsMem
+};

package/dist/conformance-tests/bs-conformance.setup.ts

@@ -0,0 +1,39 @@
+// @license
+// Copyright (c) 2026 Rljson
+//
+// Use of this source code is governed by terms that can be
+// found in the LICENSE file in the root of this package.
+
+import { BsMem, BsTestSetup } from '../src';
+
+// .............................................................................
+/**
+ * Test setup for BsMem conformance tests
+ */
+class MyBsTestSetup implements BsTestSetup {
+  bs: BsMem;
+
+  constructor() {
+    this.bs = new BsMem();
+  }
+
+  async beforeAll(): Promise<void> {
+    // Setup before all tests
+  }
+
+  async beforeEach(): Promise<void> {
+    // Clear before each test
+    this.bs.clear();
+  }
+
+  async afterEach(): Promise<void> {
+    // Cleanup after each test
+  }
+
+  async afterAll(): Promise<void> {
+    // Cleanup after all tests
+  }
+}
+
+// .............................................................................
+export const testSetup = () => new MyBsTestSetup();