@rljson/bs 0.0.18 → 0.0.20

package/dist/bs-multi.d.ts

@@ -0,0 +1,96 @@
+import { BlobProperties, Bs, DownloadBlobOptions, ListBlobsOptions, ListBlobsResult } from './bs.js';
+/**
+ * Type representing a Bs instance along with its capabilities and priority.
+ */
+export type BsMultiBs = {
+    bs: Bs;
+    id?: string;
+    priority: number;
+    read: boolean;
+    write: boolean;
+};
+/**
+ * Multi-tier Bs implementation that combines multiple underlying Bs instances
+ * with different capabilities (read, write) and priorities.
+ *
+ * Pattern: Local cache + remote server fallback
+ * - Lower priority number = checked first
+ * - Reads from highest priority readable, with hot-swapping to cache
+ * - Writes to all writable instances in parallel
+ */
+export declare class BsMulti implements Bs {
+    private _stores;
+    constructor(_stores: Array<BsMultiBs>);
+    /**
+     * Initializes the BsMulti by assigning IDs to all underlying Bs instances.
+     * All underlying Bs instances must already be initialized.
+     */
+    init(): Promise<void>;
+    /**
+     * Stores a blob in all writable Bs instances in parallel.
+     * @param content - The blob content to store
+     * @returns Promise resolving to blob properties from the first successful write
+     */
+    setBlob(content: Buffer | string | ReadableStream<Uint8Array>): Promise<BlobProperties>;
+    /**
+     * Retrieves a blob from the highest priority readable Bs instance.
+     * Hot-swaps the blob to all writable instances for caching.
+     * @param blobId - The blob identifier
+     * @param options - Download options
+     * @returns Promise resolving to blob content and properties
+     */
+    getBlob(blobId: string, options?: DownloadBlobOptions): Promise<{
+        content: Buffer;
+        properties: BlobProperties;
+    }>;
+    /**
+     * Retrieves a blob as a ReadableStream from the highest priority readable Bs instance.
+     * @param blobId - The blob identifier
+     * @returns Promise resolving to a ReadableStream
+     */
+    getBlobStream(blobId: string): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Deletes a blob from all writable Bs instances in parallel.
+     * @param blobId - The blob identifier
+     */
+    deleteBlob(blobId: string): Promise<void>;
+    /**
+     * Checks if a blob exists in any readable Bs instance.
+     * @param blobId - The blob identifier
+     * @returns Promise resolving to true if blob exists in any readable
+     */
+    blobExists(blobId: string): Promise<boolean>;
+    /**
+     * Gets blob properties from the highest priority readable Bs instance.
+     * @param blobId - The blob identifier
+     * @returns Promise resolving to blob properties
+     */
+    getBlobProperties(blobId: string): Promise<BlobProperties>;
+    /**
+     * Lists blobs by merging results from all readable Bs instances.
+     * Deduplicates by blobId (content-addressable).
+     * @param options - Listing options
+     * @returns Promise resolving to list of blobs
+     */
+    listBlobs(options?: ListBlobsOptions): Promise<ListBlobsResult>;
+    /**
+     * Generates a signed URL from the highest priority readable Bs instance.
+     * @param blobId - The blob identifier
+     * @param expiresIn - Expiration time in seconds
+     * @param permissions - Access permissions
+     * @returns Promise resolving to signed URL
+     */
+    generateSignedUrl(blobId: string, expiresIn: number, permissions?: 'read' | 'delete'): Promise<string>;
+    /**
+     * Gets the list of underlying readable Bs instances, sorted by priority.
+     */
+    get readables(): Array<BsMultiBs>;
+    /**
+     * Gets the list of underlying writable Bs instances, sorted by priority.
+     */
+    get writables(): Array<BsMultiBs>;
+    /**
+     * Example: Local cache (BsMem) + Remote server (BsPeer)
+     */
+    static example: () => Promise<BsMulti>;
+}

package/dist/bs-peer-bridge.d.ts

@@ -0,0 +1,72 @@
+import { Bs } from './bs.js';
+import { Socket } from './socket.js';
+/**
+ * Bridges Socket events to Bs method calls.
+ *
+ * This class listens to socket events and translates them into corresponding
+ * Bs method calls, automatically registering all Bs interface methods.
+ */
+export declare class BsPeerBridge {
+    private _bs;
+    private _socket;
+    private _eventHandlers;
+    private _handleConnectBound;
+    private _handleDisconnectBound;
+    constructor(_bs: Bs, _socket: Socket);
+    /**
+     * Starts the bridge by setting up connection event handlers and
+     * automatically registering all Bs methods.
+     */
+    start(): void;
+    /**
+     * Stops the bridge by removing all event handlers.
+     */
+    stop(): void;
+    /**
+     * Automatically registers all Bs interface methods as socket event handlers.
+     */
+    private _registerBsMethods;
+    /**
+     * Registers a socket event to be translated to a Bs method call.
+     * @param eventName - The socket event name (should match a Bs method name)
+     * @param bsMethodName - (Optional) The Bs method name if different from eventName
+     */
+    registerEvent(eventName: string, bsMethodName?: string): void;
+    /**
+     * Registers multiple socket events at once.
+     * @param eventNames - Array of event names to register
+     */
+    registerEvents(eventNames: string[]): void;
+    /**
+     * Unregisters a socket event handler.
+     * @param eventName - The event name to unregister
+     */
+    unregisterEvent(eventName: string | symbol): void;
+    /**
+     * Emits a result back through the socket.
+     * @param eventName - The event name to emit
+     * @param data - The data to send
+     */
+    emitToSocket(eventName: string | symbol, ...data: any[]): void;
+    /**
+     * Calls a Bs method directly and emits the result through the socket.
+     * @param bsMethodName - The Bs method to call
+     * @param socketEventName - The socket event to emit with the result
+     * @param args - Arguments to pass to the Bs method
+     */
+    callBsAndEmit(bsMethodName: string, socketEventName: string | symbol, ...args: any[]): Promise<void>;
+    private _handleConnect;
+    private _handleDisconnect;
+    /**
+     * Gets the current socket instance.
+     */
+    get socket(): Socket;
+    /**
+     * Gets the current Bs instance.
+     */
+    get bs(): Bs;
+    /**
+     * Returns whether the socket is currently connected.
+     */
+    get isConnected(): boolean;
+}

package/dist/bs-peer.d.ts

@@ -0,0 +1,77 @@
+import { BlobProperties, Bs, DownloadBlobOptions, ListBlobsOptions, ListBlobsResult } from './bs.ts';
+import { Socket } from './socket.ts';
+/**
+ * Peer implementation of the Bs interface that communicates over a socket.
+ * Allows remote access to a blob storage instance.
+ */
+export declare class BsPeer implements Bs {
+    private _socket;
+    isOpen: boolean;
+    constructor(_socket: Socket);
+    /**
+     * Initializes the Peer connection.
+     */
+    init(): Promise<void>;
+    /**
+     * Closes the Peer connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Returns a promise that resolves once the Peer connection is ready.
+     */
+    isReady(): Promise<void>;
+    /**
+     * Stores a blob from Buffer, string, or ReadableStream and returns properties.
+     * @param content - The blob content to store
+     * @returns Promise resolving to blob properties
+     */
+    setBlob(content: Buffer | string | ReadableStream<Uint8Array>): Promise<BlobProperties>;
+    /**
+     * Retrieves a blob by its ID as a Buffer.
+     * @param blobId - The unique identifier of the blob
+     * @param options - Download options
+     * @returns Promise resolving to blob content and properties
+     */
+    getBlob(blobId: string, options?: DownloadBlobOptions): Promise<{
+        content: Buffer;
+        properties: BlobProperties;
+    }>;
+    /**
+     * Retrieves a blob by its ID as a ReadableStream.
+     * @param blobId - The unique identifier of the blob
+     * @returns Promise resolving to readable stream
+     */
+    getBlobStream(blobId: string): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Deletes a blob by its ID.
+     * @param blobId - The unique identifier of the blob
+     * @returns Promise that resolves when deletion is complete
+     */
+    deleteBlob(blobId: string): Promise<void>;
+    /**
+     * Checks if a blob exists.
+     * @param blobId - The unique identifier of the blob
+     * @returns Promise resolving to true if blob exists
+     */
+    blobExists(blobId: string): Promise<boolean>;
+    /**
+     * Gets blob properties (size, createdAt) without retrieving content.
+     * @param blobId - The unique identifier of the blob
+     * @returns Promise resolving to blob properties
+     */
+    getBlobProperties(blobId: string): Promise<BlobProperties>;
+    /**
+     * Lists all blobs with optional filtering and pagination.
+     * @param options - Optional listing configuration
+     * @returns Promise resolving to list of blobs
+     */
+    listBlobs(options?: ListBlobsOptions): Promise<ListBlobsResult>;
+    /**
+     * Generates a signed URL for temporary blob access.
+     * @param blobId - The unique identifier of the blob
+     * @param expiresIn - Expiration time in seconds
+     * @param permissions - Permissions for the URL
+     * @returns Promise resolving to signed URL
+     */
+    generateSignedUrl(blobId: string, expiresIn: number, permissions?: 'read' | 'delete'): Promise<string>;
+}

package/dist/bs-server.d.ts

@@ -0,0 +1,32 @@
+import { Bs } from './bs.ts';
+import { Socket } from './socket.ts';
+/**
+ * Server implementation that exposes a Bs instance over socket connections.
+ * Allows multiple clients to access the same blob storage instance remotely.
+ */
+export declare class BsServer {
+    private readonly _bs;
+    private _sockets;
+    constructor(_bs: Bs);
+    /**
+     * Adds a socket to the BsServer instance.
+     * @param socket - The socket to add.
+     */
+    addSocket(socket: Socket): Promise<void>;
+    /**
+     * Removes a socket from the BsServer instance.
+     * @param socket - The socket to remove.
+     */
+    removeSocket(socket: Socket): void;
+    /**
+     * Adds a transport layer to the given socket.
+     * @param socket - The socket to add the transport layer to.
+     */
+    private _addTransportLayer;
+    /**
+     * Generates a transport layer object for the given Bs instance.
+     * @param bs - The Bs instance to generate the transport layer for.
+     * @returns An object containing methods that correspond to the Bs interface.
+     */
+    private _generateTransportLayer;
+}