@spooky-sync/core 0.0.0-canary.1 → 0.0.1-canary.4

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId, Surreal, SurrealTransaction } from "surrealdb";
-import { AccessDefinition, BackendNames, BackendRoutes, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RecordId as RecordId$1, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
+import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RecordId as RecordId$1, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
 import { Level, Level as Level$1, Logger } from "pino";
 
 //#region src/events/index.d.ts
@@ -544,6 +544,19 @@ declare class AuthService<S extends SchemaStructure> {
 }
 //#endregion
 //#region src/spooky.d.ts
+declare class BucketHandle {
+  private bucketName;
+  private remote;
+  constructor(bucketName: string, remote: RemoteDatabaseService);
+  put(path: string, content: string | Uint8Array | Blob): Promise<void>;
+  get(path: string): Promise<unknown>;
+  delete(path: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  head(path: string): Promise<Record<string, unknown>>;
+  copy(sourcePath: string, targetPath: string): Promise<void>;
+  rename(sourcePath: string, targetPath: string): Promise<void>;
+  list(prefix?: string): Promise<string[]>;
+}
 declare class SpookyClient<S extends SchemaStructure> {
   private config;
   private local;
@@ -577,6 +590,7 @@ declare class SpookyClient<S extends SchemaStructure> {
     immediate?: boolean;
   }): Promise<() => void>;
   run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
+  bucket<B extends BucketNames<S>>(name: B): BucketHandle;
   create(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
   update(table: string, id: string, data: Record<string, unknown>, options?: UpdateOptions): Promise<{
     [x: string]: /*elided*/any;
@@ -587,4 +601,11 @@ declare class SpookyClient<S extends SchemaStructure> {
   private loadOrGenerateClientId;
 }
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, DebounceOptions, EventSubscriptionOptions, type Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, SpookyClient, SpookyConfig, SpookyQueryResult, SpookyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem };
+//#region src/utils/index.d.ts
+declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
+/**
+ * Helper for retrying DB operations with exponential backoff
+ */
+
+//#endregion
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, DebounceOptions, EventSubscriptionOptions, type Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, SpookyClient, SpookyConfig, SpookyQueryResult, SpookyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, fileToUint8Array };

package/dist/index.js

@@ -169,6 +169,10 @@ function parseDuration(duration) {
 		default: return val * 6e4;
 	}
 }
+async function fileToUint8Array(file) {
+	const buffer = await file.arrayBuffer();
+	return new Uint8Array(buffer);
+}
 /**
 * Helper for retrying DB operations with exponential backoff
 */
@@ -204,6 +208,7 @@ async function withRetry(logger, operation, retries = 3, delayMs = 100) {
 */
 var DataModule = class {
 	activeQueries = /* @__PURE__ */ new Map();
+	pendingQueries = /* @__PURE__ */ new Map();
 	subscriptions = /* @__PURE__ */ new Map();
 	mutationCallbacks = /* @__PURE__ */ new Set();
 	debounceTimers = /* @__PURE__ */ new Map();
@@ -238,36 +243,25 @@ var DataModule = class {
 			}, "Query Initialization: exists, returning");
 			return hash;
 		}
+		if (this.pendingQueries.has(hash)) {
+			this.logger.debug({
+				hash,
+				Category: "spooky-client::DataModule::query"
+			}, "Query Initialization: pending, waiting for existing creation");
+			await this.pendingQueries.get(hash);
+			return hash;
+		}
 		this.logger.debug({
 			hash,
 			Category: "spooky-client::DataModule::query"
 		}, "Query Initialization: not found, creating new query");
-		const queryState = await this.createNewQuery({
-			recordId,
-			surql: surqlString,
-			params,
-			ttl,
-			tableName
-		});
-		const { localArray } = this.cache.registerQuery({
-			queryHash: hash,
-			surql: surqlString,
-			params,
-			ttl: new Duration(ttl),
-			lastActiveAt: /* @__PURE__ */ new Date()
-		});
-		await withRetry(this.logger, () => this.local.query(surql.seal(surql.updateSet("id", ["localArray"])), {
-			id: recordId,
-			localArray
-		}));
-		this.activeQueries.set(hash, queryState);
-		this.startTTLHeartbeat(queryState);
-		this.logger.debug({
-			hash,
-			tableName,
-			recordCount: queryState.records.length,
-			Category: "spooky-client::DataModule::query"
-		}, "Query registered");
+		const promise = this.createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName);
+		this.pendingQueries.set(hash, promise);
+		try {
+			await promise;
+		} finally {
+			this.pendingQueries.delete(hash);
+		}
 		return hash;
 	}
 	/**
@@ -323,13 +317,23 @@ var DataModule = class {
 		}
 		try {
 			const [records] = await this.local.query(queryState.config.surql, queryState.config.params);
-			queryState.records = records || [];
+			const newRecords = records || [];
 			queryState.config.localArray = localArray;
-			queryState.updateCount++;
 			await this.local.query(surql.seal(surql.updateSet("id", ["localArray"])), {
 				id: queryState.config.id,
 				localArray
 			});
+			const prevJson = JSON.stringify(queryState.records);
+			const newJson = JSON.stringify(newRecords);
+			queryState.records = newRecords;
+			if (prevJson === newJson) {
+				this.logger.debug({
+					queryHash,
+					Category: "spooky-client::DataModule::onStreamUpdate"
+				}, "Query records unchanged, skipping notification");
+				return;
+			}
+			queryState.updateCount++;
 			const subscribers = this.subscriptions.get(queryHash);
 			if (subscribers) for (const callback of subscribers) callback(queryState.records);
 			this.logger.debug({
@@ -393,6 +397,23 @@ var DataModule = class {
 			remoteArray
 		});
 	}
+	/**
+	* Called after a query's initial sync completes.
+	* Ensures subscribers are notified even if no stream updates fired (e.g. empty result set).
+	*/
+	async notifyQuerySynced(queryHash) {
+		const queryState = this.activeQueries.get(queryHash);
+		if (!queryState) return;
+		const [records] = await this.local.query(queryState.config.surql, queryState.config.params);
+		const newRecords = records || [];
+		const changed = JSON.stringify(queryState.records) !== JSON.stringify(newRecords);
+		queryState.records = newRecords;
+		if (changed || queryState.updateCount === 0) {
+			queryState.updateCount++;
+			const subscribers = this.subscriptions.get(queryHash);
+			if (subscribers) for (const callback of subscribers) callback(queryState.records);
+		}
+	}
 	async run(backend, path, data, options) {
 		const route = this.schema.backends?.[backend]?.routes?.[path];
 		if (!route) throw new Error(`Route ${backend}.${path} not found`);
@@ -482,7 +503,10 @@ var DataModule = class {
 			mid: mutationId,
 			data: params
 		}));
-		this.replaceRecordInQueries(target);
+		const updatedFields = { id: target.id };
+		for (const key of Object.keys(data)) if (key in target) updatedFields[key] = target[key];
+		if ("spooky_rv" in target) updatedFields.spooky_rv = target.spooky_rv;
+		this.replaceRecordInQueries(updatedFields);
 		const parsedRecord = parseParams(tableSchema.columns, target);
 		await this.cache.save({
 			table,
@@ -605,6 +629,35 @@ var DataModule = class {
 			}
 		}
 	}
+	async createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName) {
+		const queryState = await this.createNewQuery({
+			recordId,
+			surql: surqlString,
+			params,
+			ttl,
+			tableName
+		});
+		const { localArray } = this.cache.registerQuery({
+			queryHash: hash,
+			surql: surqlString,
+			params,
+			ttl: new Duration(ttl),
+			lastActiveAt: /* @__PURE__ */ new Date()
+		});
+		await withRetry(this.logger, () => this.local.query(surql.seal(surql.updateSet("id", ["localArray"])), {
+			id: recordId,
+			localArray
+		}));
+		this.activeQueries.set(hash, queryState);
+		this.startTTLHeartbeat(queryState);
+		this.logger.debug({
+			hash,
+			tableName,
+			recordCount: queryState.records.length,
+			Category: "spooky-client::DataModule::query"
+		}, "Query registered");
+		return hash;
+	}
 	async createNewQuery({ recordId, surql: surqlString, params, ttl, tableName }) {
 		const tableSchema = this.schema.tables.find((t) => t.name === tableName);
 		if (!tableSchema) throw new Error(`Table ${tableName} not found`);
@@ -671,11 +724,17 @@ var DataModule = class {
 		}
 	}
 	async replaceRecordInQueries(record) {
-		for (const queryState of this.activeQueries.values()) this.replaceRecordInQuery(queryState, record);
-	}
-	replaceRecordInQuery(queryState, record) {
-		const index = queryState.records.findIndex((r) => r.id === record.id);
-		if (index !== -1) queryState.records[index] = record;
+		for (const [queryHash, queryState] of this.activeQueries.entries()) {
+			const index = queryState.records.findIndex((r) => r.id === record.id);
+			if (index !== -1) {
+				queryState.records[index] = {
+					...queryState.records[index],
+					...record
+				};
+				const subscribers = this.subscriptions.get(queryHash);
+				if (subscribers) for (const callback of subscribers) callback(queryState.records);
+			}
+		}
 	}
 };
 /**
@@ -1966,6 +2025,7 @@ var SpookySync = class {
 			}, "Register Query state");
 			await this.createRemoteQuery(queryHash);
 			await this.syncQuery(queryHash);
+			await this.dataModule.notifyQuerySynced(queryHash);
 		} catch (e) {
 			this.logger.error({
 				err: e,
@@ -2912,6 +2972,41 @@ var SurrealDBPersistenceClient = class {
 
 //#endregion
 //#region src/spooky.ts
+var BucketHandle = class {
+	constructor(bucketName, remote) {
+		this.bucketName = bucketName;
+		this.remote = remote;
+	}
+	async put(path, content) {
+		await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
+	}
+	async get(path) {
+		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".get();`);
+		return result;
+	}
+	async delete(path) {
+		await this.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
+	}
+	async exists(path) {
+		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".exists();`);
+		return result;
+	}
+	async head(path) {
+		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".head();`);
+		return result;
+	}
+	async copy(sourcePath, targetPath) {
+		await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, { target: targetPath });
+	}
+	async rename(sourcePath, targetPath) {
+		await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, { target: targetPath });
+	}
+	async list(prefix) {
+		const p = prefix ?? "";
+		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${p}".list();`);
+		return result;
+	}
+};
 var SpookyClient = class {
 	local;
 	remote;
@@ -3047,6 +3142,9 @@ var SpookyClient = class {
 	run(backend, path, payload, options) {
 		return this.dataModule.run(backend, path, payload, options);
 	}
+	bucket(name) {
+		return new BucketHandle(name, this.remote);
+	}
 	create(id, data) {
 		return this.dataModule.create(id, data);
 	}
@@ -3079,4 +3177,4 @@ var SpookyClient = class {
 };
 
 //#endregion
-export { AuthEventTypes, AuthService, SpookyClient, createAuthEventSystem };
+export { AuthEventTypes, AuthService, BucketHandle, SpookyClient, createAuthEventSystem, fileToUint8Array };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.0-canary.1",
+  "version": "0.0.1-canary.4",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -43,4 +43,4 @@
     "typescript": "^5.6.2",
     "vitest": "^3.2.0"
   }
-}
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './spooky';
 export * from './modules/auth/index';
+export { fileToUint8Array } from './utils/index';

package/src/modules/data/index.ts

@@ -45,6 +45,7 @@ import { PushEventOptions } from '../../events/index';
  */
 export class DataModule<S extends SchemaStructure> {
   private activeQueries: Map<QueryHash, QueryState> = new Map();
+  private pendingQueries: Map<QueryHash, Promise<QueryHash>> = new Map();
   private subscriptions: Map<QueryHash, Set<QueryUpdateCallback>> = new Map();
   private mutationCallbacks: Set<MutationCallback> = new Set();
   private debounceTimers: Map<QueryHash, NodeJS.Timeout> = new Map();
@@ -91,44 +92,29 @@ export class DataModule<S extends SchemaStructure> {
       return hash;
     }
 
+    // Another call is already creating this query — wait for it
+    if (this.pendingQueries.has(hash)) {
+      this.logger.debug(
+        { hash, Category: 'spooky-client::DataModule::query' },
+        'Query Initialization: pending, waiting for existing creation'
+      );
+      await this.pendingQueries.get(hash);
+      return hash;
+    }
+
     this.logger.debug(
       { hash, Category: 'spooky-client::DataModule::query' },
       'Query Initialization: not found, creating new query'
     );
-    const queryState = await this.createNewQuery<T>({
-      recordId,
-      surql: surqlString,
-      params,
-      ttl,
-      tableName,
-    });
-
-    const { localArray } = this.cache.registerQuery({
-      queryHash: hash,
-      surql: surqlString,
-      params,
-      ttl: new Duration(ttl),
-      lastActiveAt: new Date(),
-    });
-
-    await withRetry(this.logger, () =>
-      this.local.query(surql.seal(surql.updateSet('id', ['localArray'])), {
-        id: recordId,
-        localArray,
-      })
-    );
 
-    this.activeQueries.set(hash, queryState);
-    this.startTTLHeartbeat(queryState);
-    this.logger.debug(
-      {
-        hash,
-        tableName,
-        recordCount: queryState.records.length,
-        Category: 'spooky-client::DataModule::query',
-      },
-      'Query registered'
-    );
+    // Create the query and track the pending promise
+    const promise = this.createAndRegisterQuery<T>(hash, recordId, surqlString, params, ttl, tableName);
+    this.pendingQueries.set(hash, promise);
+    try {
+      await promise;
+    } finally {
+      this.pendingQueries.delete(hash);
+    }
 
     return hash;
   }
@@ -222,14 +208,27 @@ export class DataModule<S extends SchemaStructure> {
       );
 
       // Update state
-      queryState.records = records || [];
+      const newRecords = records || [];
       queryState.config.localArray = localArray;
-      queryState.updateCount++;
       await this.local.query(surql.seal(surql.updateSet('id', ['localArray'])), {
         id: queryState.config.id,
         localArray,
       });
 
+      // Skip notification if records haven't changed
+      const prevJson = JSON.stringify(queryState.records);
+      const newJson = JSON.stringify(newRecords);
+      queryState.records = newRecords;
+      if (prevJson === newJson) {
+        this.logger.debug(
+          { queryHash, Category: 'spooky-client::DataModule::onStreamUpdate' },
+          'Query records unchanged, skipping notification'
+        );
+        return;
+      }
+
+      queryState.updateCount++;
+
       // Notify subscribers
       const subscribers = this.subscriptions.get(queryHash);
       if (subscribers) {
@@ -307,6 +306,36 @@ export class DataModule<S extends SchemaStructure> {
     });
   }
 
+  /**
+   * Called after a query's initial sync completes.
+   * Ensures subscribers are notified even if no stream updates fired (e.g. empty result set).
+   */
+  async notifyQuerySynced(queryHash: string): Promise<void> {
+    const queryState = this.activeQueries.get(queryHash);
+    if (!queryState) return;
+
+    // Re-query local DB for latest data
+    const [records] = await this.local.query<[Record<string, any>[]]>(
+      queryState.config.surql,
+      queryState.config.params
+    );
+    const newRecords = records || [];
+    const changed = JSON.stringify(queryState.records) !== JSON.stringify(newRecords);
+    queryState.records = newRecords;
+
+    // Notify if data changed OR if this is the first sync (updateCount === 0)
+    // The latter handles "query truly has no results" so UI can stop loading
+    if (changed || queryState.updateCount === 0) {
+      queryState.updateCount++;
+      const subscribers = this.subscriptions.get(queryHash);
+      if (subscribers) {
+        for (const callback of subscribers) {
+          callback(queryState.records);
+        }
+      }
+    }
+  }
+
   // ====================      RUN JOBS       ====================
 
   async run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
@@ -458,10 +487,19 @@ export class DataModule<S extends SchemaStructure> {
       })
     );
 
-    // Replace record in all queries directly
-    // Does not respect sorting or other advanced query features
-    // But is fast for quick typing for example
-    this.replaceRecordInQueries(target);
+    // Build a partial record with only the fields the user actually changed
+    // This avoids overwriting rich relation objects (e.g. author: {id, name, ...})
+    // with flat RecordIds from the UPDATE...MERGE result
+    const updatedFields: Record<string, any> = { id: target.id };
+    for (const key of Object.keys(data)) {
+      if (key in target) {
+        updatedFields[key] = (target as Record<string, any>)[key];
+      }
+    }
+    if ('spooky_rv' in (target as Record<string, any>)) {
+      updatedFields.spooky_rv = (target as Record<string, any>).spooky_rv;
+    }
+    this.replaceRecordInQueries(updatedFields);
 
     const parsedRecord = parseParams(tableSchema.columns, target) as RecordWithId;
 
@@ -634,6 +672,52 @@ export class DataModule<S extends SchemaStructure> {
 
   // ==================== PRIVATE HELPERS ====================
 
+  private async createAndRegisterQuery<T extends TableNames<S>>(
+    hash: QueryHash,
+    recordId: RecordId,
+    surqlString: string,
+    params: Record<string, any>,
+    ttl: QueryTimeToLive,
+    tableName: T
+  ): Promise<QueryHash> {
+    const queryState = await this.createNewQuery<T>({
+      recordId,
+      surql: surqlString,
+      params,
+      ttl,
+      tableName,
+    });
+
+    const { localArray } = this.cache.registerQuery({
+      queryHash: hash,
+      surql: surqlString,
+      params,
+      ttl: new Duration(ttl),
+      lastActiveAt: new Date(),
+    });
+
+    await withRetry(this.logger, () =>
+      this.local.query(surql.seal(surql.updateSet('id', ['localArray'])), {
+        id: recordId,
+        localArray,
+      })
+    );
+
+    this.activeQueries.set(hash, queryState);
+    this.startTTLHeartbeat(queryState);
+    this.logger.debug(
+      {
+        hash,
+        tableName,
+        recordCount: queryState.records.length,
+        Category: 'spooky-client::DataModule::query',
+      },
+      'Query registered'
+    );
+
+    return hash;
+  }
+
   private async createNewQuery<T extends TableNames<S>>({
     recordId,
     surql: surqlString,
@@ -736,15 +820,18 @@ export class DataModule<S extends SchemaStructure> {
   }
 
   private async replaceRecordInQueries(record: Record<string, any>): Promise<void> {
-    for (const queryState of this.activeQueries.values()) {
-      this.replaceRecordInQuery(queryState, record);
-    }
-  }
-
-  private replaceRecordInQuery(queryState: QueryState, record: Record<string, any>): void {
-    const index = queryState.records.findIndex((r) => r.id === record.id);
-    if (index !== -1) {
-      queryState.records[index] = record;
+    for (const [queryHash, queryState] of this.activeQueries.entries()) {
+      const index = queryState.records.findIndex((r) => r.id === record.id);
+      if (index !== -1) {
+        queryState.records[index] = { ...queryState.records[index], ...record };
+        // Notify subscribers so UI updates immediately
+        const subscribers = this.subscriptions.get(queryHash);
+        if (subscribers) {
+          for (const callback of subscribers) {
+            callback(queryState.records);
+          }
+        }
+      }
     }
   }
 }

package/src/modules/sync/sync.ts

@@ -314,6 +314,9 @@ export class SpookySync<S extends SchemaStructure> {
       );
       await this.createRemoteQuery(queryHash);
       await this.syncQuery(queryHash);
+      // Always notify after sync completes — handles empty result sets
+      // where no stream updates fire but the UI needs to stop loading
+      await this.dataModule.notifyQuerySynced(queryHash);
     } catch (e) {
       this.logger.error(
         { err: e, Category: 'spooky-client::SpookySync::registerQuery' },

package/src/spooky.ts

@@ -23,6 +23,7 @@ import {
   SchemaStructure,
   TableModel,
   TableNames,
+  BucketNames,
   BackendNames,
   BackendRoutes,
   RoutePayload,
@@ -38,6 +39,47 @@ import { LocalStoragePersistenceClient } from './services/persistence/localstora
 import { generateId, parseParams } from './utils/index';
 import { SurrealDBPersistenceClient } from './services/persistence/surrealdb';
 
+export class BucketHandle {
+  constructor(private bucketName: string, private remote: RemoteDatabaseService) {}
+
+  async put(path: string, content: string | Uint8Array | Blob): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
+  }
+
+  async get(path: string): Promise<unknown> {
+    const [result] = await this.remote.query<[unknown]>(`RETURN f"${this.bucketName}:/${path}".get();`);
+    return result;
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const [result] = await this.remote.query<[boolean]>(`RETURN f"${this.bucketName}:/${path}".exists();`);
+    return result;
+  }
+
+  async head(path: string): Promise<Record<string, unknown>> {
+    const [result] = await this.remote.query<[Record<string, unknown>]>(`RETURN f"${this.bucketName}:/${path}".head();`);
+    return result;
+  }
+
+  async copy(sourcePath: string, targetPath: string): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, { target: targetPath });
+  }
+
+  async rename(sourcePath: string, targetPath: string): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, { target: targetPath });
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const p = prefix ?? '';
+    const [result] = await this.remote.query<[string[]]>(`RETURN f"${this.bucketName}:/${p}".list();`);
+    return result;
+  }
+}
+
 export class SpookyClient<S extends SchemaStructure> {
   private local: LocalDatabaseService;
   private remote: RemoteDatabaseService;
@@ -305,6 +347,10 @@ export class SpookyClient<S extends SchemaStructure> {
     return this.dataModule.run(backend, path, payload, options);
   }
 
+  bucket<B extends BucketNames<S>>(name: B): BucketHandle {
+    return new BucketHandle(name, this.remote);
+  }
+
   create(id: string, data: Record<string, unknown>) {
     return this.dataModule.create(id, data);
   }

package/src/utils/index.ts

@@ -130,6 +130,13 @@ export function parseDuration(duration: QueryTimeToLive | Duration): number {
   }
 }
 
+// ==================== FILE UTILITIES ====================
+
+export async function fileToUint8Array(file: File | Blob): Promise<Uint8Array> {
+  const buffer = await file.arrayBuffer();
+  return new Uint8Array(buffer);
+}
+
 // ==================== DATABASE UTILITIES ====================
 
 /**