feat: string offloading support

Strings longer than maxStringLength (default 32768) are offloaded
to blob storage on upload, and resolved back to string on read.

- New config option: maxStringLength
- BlobManager handles _bt:'string' upload (UTF-8) and download (TextDecoder)
- DexieCloudConfig extended with maxStringLength

Author: liz709

package-lock.json

@@ -109,11 +109,15 @@ function uint8ArrayToBase64(data: Uint8Array): string {
   return btoa(binary);
 }
 
+/** Default max string length before offloading */
+export const DEFAULT_MAX_STRING_LENGTH = 32768;
+
 export class BlobManager {
   constructor(
     private dbUrl: string,
     private http: HttpAdapter,
-    private mode: BlobHandling = 'auto'
+    private mode: BlobHandling = 'auto',
+    private maxStringLength: number = DEFAULT_MAX_STRING_LENGTH
   ) {}
 
   /**
@@ -214,6 +218,13 @@ export class BlobManager {
   }
 
   private async _walkForUpload(val: any, token: string): Promise<any> {
+    // Check long strings
+    if (typeof val === 'string' && val.length > this.maxStringLength && this.maxStringLength !== Infinity) {
+      const bytes = new TextEncoder().encode(val);
+      const ref = await this.upload(bytes, token, 'text/plain;charset=utf-8');
+      return { _bt: 'string', ref, size: bytes.length } as BlobRef;
+    }
+
     if (isInlineBlob(val)) {
       const bytes = base64ToUint8Array(val.v);
       // Only offload to blob storage if the binary meets the size threshold.
@@ -249,6 +260,11 @@ export class BlobManager {
 
   private async _walkForRead(val: any, token: string): Promise<any> {
     if (isBlobRef(val)) {
+      // String type: download and decode UTF-8 back to string
+      if (val._bt === 'string') {
+        const { data } = await this.download(val.ref, token);
+        return new TextDecoder().decode(data);
+      }
       const { data, contentType } = await this.download(val.ref, token);
       return {
         _bt: val._bt,

src/blob.ts

@@ -43,7 +43,7 @@ export class DexieCloudClient {
 
     // Use dbUrl if provided, otherwise fall back to serviceUrl
     const dbUrl = fullConfig.dbUrl ?? fullConfig.serviceUrl;
-    this.blobs = new BlobManager(dbUrl, this.http, fullConfig.blobHandling ?? 'auto');
+    this.blobs = new BlobManager(dbUrl, this.http, fullConfig.blobHandling ?? 'auto', fullConfig.maxStringLength ?? 32768);
     // Pass BlobManager to DataManager so create/get/list auto-process blobs
     this.data = new DataManager(dbUrl, this.http, this.blobs);
   }

src/client.ts

@@ -18,6 +18,13 @@ export interface DexieCloudConfig {
 
   /** Blob handling mode: 'auto' (default) or 'lazy' */
   blobHandling?: BlobHandling;
+
+  /** Maximum string length before offloading to blob storage.
+   * Strings longer than this are uploaded as blobs during write.
+   * Set to Infinity to disable string offloading.
+   * @default 32768
+   */
+  maxStringLength?: number;
 
   /** Optional custom fetch implementation */
   fetch?: typeof globalThis.fetch;