@edgespark/server-types 0.0.1-alpha.2 → 0.0.1-alpha.3

package/dist/index.d.ts

@@ -89,42 +89,130 @@ export interface StorageClient {
      */
     from(bucket: BucketDef): BucketClient;
 }
+/**
+ * Options for listing files in a bucket
+ *
+ * @example
+ * // Setup: import buckets from @generated, get BucketClient via from()
+ * import { buckets } from '@generated';
+ * const bucket = edgespark.storage.from(buckets.files); // BucketDef, not string!
+ *
+ * // List all files
+ * await bucket.list()
+ *
+ * // Filter by prefix (e.g., get all files for a user)
+ * await bucket.list({ prefix: 'user-123/' })
+ *
+ * // Pagination
+ * const page1 = await bucket.list({ limit: 100 })
+ * if (page1.hasMore) {
+ *   const page2 = await bucket.list({ limit: 100, cursor: page1.cursor })
+ * }
+ *
+ * // Folder-like listing with delimiter
+ * // Use delimiter: '/' to group files into "folders"
+ * const { objects, delimitedPrefixes } = await bucket.list({
+ *   prefix: 'documents/',
+ *   delimiter: '/'
+ * })
+ * // objects = files directly in documents/ (e.g., 'documents/readme.txt')
+ * // delimitedPrefixes = subfolders (e.g., ['documents/api/', 'documents/guides/'])
+ */
+export interface StorageListOptions {
+    /** Maximum number of files to return (default: 1000, max: 1000) */
+    limit?: number;
+    /** Only return files whose keys start with this prefix (e.g., 'user-123/' or 'images/') */
+    prefix?: string;
+    /** Pagination token from previous result.cursor. Use to get next page of results */
+    cursor?: string;
+    /**
+     * Character to group keys by (usually '/'). When set, keys containing the delimiter
+     * after the prefix are grouped and returned in result.delimitedPrefixes instead of result.objects.
+     * This enables folder-like browsing of storage.
+     */
+    delimiter?: string;
+}
 export interface BucketClient {
     /**
      * Upload file (<100MB). Use createPresignedPutUrl for large files.
-     * @example await bucket.put('photo.jpg', buffer, { contentType: 'image/jpeg' });
+     * @example
+     * import { buckets } from '@generated';
+     * const bucket = edgespark.storage.from(buckets.avatars);
+     * await bucket.put('photo.jpg', buffer, { contentType: 'image/jpeg' });
      */
     put(path: string, file: ArrayBuffer, options?: StorageHttpMetadata): Promise<{
         success: boolean;
     }>;
     /**
      * Download file. Returns null if not found.
-     * @example const file = await bucket.get('doc.pdf'); if (file) { ... }
+     * @example
+     * import { buckets } from '@generated';
+     * const bucket = edgespark.storage.from(buckets.documents);
+     * const file = await bucket.get('doc.pdf');
+     * if (file) {
+     *   // file.body is ArrayBuffer, file.metadata has size and httpMetadata
+     * }
      */
     get(path: string): Promise<StorageObject | null>;
     /**
      * Get metadata only (no body). Faster than get() for existence checks.
-     * @example const meta = await bucket.head('file.txt'); if (meta) { ... }
+     * @example
+     * import { buckets } from '@generated';
+     * const bucket = edgespark.storage.from(buckets.uploads);
+     * const meta = await bucket.head('file.txt');
+     * if (meta) {
+     *   console.log(meta.size, meta.httpMetadata.contentType);
+     * }
      */
     head(path: string): Promise<StorageObjectMetadata | null>;
     /**
-     * List files with optional prefix filter
-     * @example const { objects, hasMore, cursor } = await bucket.list('user-123/');
+     * List files with optional filtering and pagination
+     *
+     * @param options - See {@link StorageListOptions} for all options
+     * @returns {@link StorageListResult} with objects, hasMore, cursor, delimitedPrefixes
+     *
+     * @example
+     * // First: get BucketClient from BucketDef (not string!)
+     * import { buckets } from '@generated';
+     * const bucket = edgespark.storage.from(buckets.uploads);
+     *
+     * // List user's files
+     * const { objects } = await bucket.list({ prefix: 'user-123/' })
+     *
+     * // Paginated listing
+     * let cursor: string | undefined
+     * do {
+     *   const result = await bucket.list({ limit: 100, cursor })
+     *   cursor = result.hasMore ? result.cursor : undefined
+     * } while (cursor)
+     *
+     * // Folder browser (delimiter returns subfolders in delimitedPrefixes)
+     * const { objects, delimitedPrefixes } = await bucket.list({
+     *   prefix: 'photos/',
+     *   delimiter: '/'
+     * })
      */
-    list(prefix?: string, options?: {
-        limit?: number;
-        cursor?: string;
-    }): Promise<StorageListResult>;
+    list(options?: StorageListOptions): Promise<StorageListResult>;
     /**
      * Delete file(s). Supports bulk delete up to 1000 paths.
-     * @example await bucket.delete(['file1.jpg', 'file2.jpg']);
+     * @example
+     * import { buckets } from '@generated';
+     * const bucket = edgespark.storage.from(buckets.temp);
+     * // Single file
+     * await bucket.delete('old-file.txt');
+     * // Bulk delete
+     * await bucket.delete(['file1.jpg', 'file2.jpg', 'file3.jpg']);
      */
     delete(paths: string | string[]): Promise<{
         success: boolean;
     }>;
     /**
-     * Generate presigned upload URL for direct client uploads
-     * @example const { uploadUrl } = await bucket.createPresignedPutUrl('video.mp4', 3600);
+     * Generate presigned upload URL for direct client uploads (bypasses worker, uploads directly to R2)
+     * @example
+     * import { buckets } from '@generated';
+     * const bucket = edgespark.storage.from(buckets.videos);
+     * const { uploadUrl, expiresAt } = await bucket.createPresignedPutUrl('video.mp4', 3600);
+     * // Return uploadUrl to client, client uploads directly via PUT request
      */
     createPresignedPutUrl(path: string, expiresInSecs?: number, options?: StorageHttpMetadata): Promise<{
         uploadUrl: string;
@@ -132,8 +220,12 @@ export interface BucketClient {
         expiresAt: Date;
     }>;
     /**
-     * Generate presigned download URL for direct client downloads
-     * @example const { downloadUrl } = await bucket.createPresignedGetUrl('video.mp4', 3600);
+     * Generate presigned download URL for direct client downloads (bypasses worker, downloads directly from R2)
+     * @example
+     * import { buckets } from '@generated';
+     * const bucket = edgespark.storage.from(buckets.videos);
+     * const { downloadUrl, expiresAt } = await bucket.createPresignedGetUrl('video.mp4', 3600);
+     * // Return downloadUrl to client for direct download
      */
     createPresignedGetUrl(path: string, expiresInSecs?: number): Promise<{
         downloadUrl: string;
@@ -155,14 +247,47 @@ export interface StorageObject {
     body: ArrayBuffer;
     metadata: StorageObjectMetadata;
 }
+/** File info returned in StorageListResult.objects */
 export interface StorageFileInfo {
+    /** Full path of the file (e.g., 'user-123/photos/image.jpg') */
     key: string;
+    /** File size in bytes */
     size: number;
+    /** Upload timestamp */
     uploaded: Date;
 }
+/**
+ * Result from bucket.list() operation
+ *
+ * @example
+ * import { buckets } from '@generated';
+ * const bucket = edgespark.storage.from(buckets.files); // BucketDef, not string!
+ *
+ * const result = await bucket.list({ prefix: 'user-123/', delimiter: '/' })
+ *
+ * // Files matching the query
+ * result.objects.forEach(file => {
+ *   console.log(file.key)      // 'user-123/photo.jpg'
+ *   console.log(file.size)     // 1024 (bytes)
+ *   console.log(file.uploaded) // Date object
+ * })
+ *
+ * // Pagination
+ * if (result.hasMore) {
+ *   const nextPage = await bucket.list({ cursor: result.cursor })
+ * }
+ *
+ * // Subfolders (only when delimiter is used)
+ * result.delimitedPrefixes // ['user-123/photos/', 'user-123/documents/']
+ */
 export interface StorageListResult {
+    /** Array of file objects matching the query */
     objects: StorageFileInfo[];
+    /** True if more results available. Use cursor to fetch next page */
     hasMore: boolean;
+    /** Pagination token. Pass to next list() call to get more results. Only present when hasMore is true */
     cursor?: string;
+    /** Common prefixes (subfolders) when delimiter option is used. Empty array if no delimiter specified */
+    delimitedPrefixes: string[];
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgespark/server-types",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.1-alpha.3",
   "description": "Type definitions for EdgeSpark server SDK",
   "keywords": [
     "edgespark",