@supabase/storage-js 2.79.1-canary.1 → 2.80.0

package/src/lib/vectors/types.ts

@@ -0,0 +1,299 @@
+import { StorageVectorsError } from './errors'
+
+/**
+ * Configuration for encryption at rest
+ * @property kmsKeyArn - ARN of the KMS key used for encryption
+ * @property sseType - Server-side encryption type (e.g., 'KMS')
+ */
+export interface EncryptionConfiguration {
+  kmsKeyArn?: string
+  sseType?: string
+}
+
+/**
+ * Vector bucket metadata
+ * @property vectorBucketName - Unique name of the vector bucket
+ * @property creationTime - Unix timestamp of when the bucket was created
+ * @property encryptionConfiguration - Optional encryption settings
+ */
+export interface VectorBucket {
+  vectorBucketName: string
+  creationTime?: number
+  encryptionConfiguration?: EncryptionConfiguration
+}
+
+/**
+ * Metadata configuration for vector index
+ * Defines which metadata keys should not be indexed for filtering
+ * @property nonFilterableMetadataKeys - Array of metadata keys that cannot be used in filters
+ */
+export interface MetadataConfiguration {
+  nonFilterableMetadataKeys?: string[]
+}
+
+/**
+ * Supported data types for vectors
+ * Currently only float32 is supported
+ */
+export type VectorDataType = 'float32'
+
+/**
+ * Distance metrics for vector similarity search
+ */
+export type DistanceMetric = 'cosine' | 'euclidean' | 'dotproduct'
+
+/**
+ * Vector index configuration and metadata
+ * @property indexName - Unique name of the index within the bucket
+ * @property vectorBucketName - Name of the parent vector bucket
+ * @property dataType - Data type of vector components (currently only 'float32')
+ * @property dimension - Dimensionality of vectors (e.g., 384, 768, 1536)
+ * @property distanceMetric - Similarity metric used for queries
+ * @property metadataConfiguration - Configuration for metadata filtering
+ * @property creationTime - Unix timestamp of when the index was created
+ */
+export interface VectorIndex {
+  indexName: string
+  vectorBucketName: string
+  dataType: VectorDataType
+  dimension: number
+  distanceMetric: DistanceMetric
+  metadataConfiguration?: MetadataConfiguration
+  creationTime?: number
+}
+
+/**
+ * Vector data representation
+ * Vectors must be float32 arrays with dimensions matching the index
+ * @property float32 - Array of 32-bit floating point numbers
+ */
+export interface VectorData {
+  float32: number[]
+}
+
+/**
+ * Arbitrary JSON metadata attached to vectors
+ * Keys configured as non-filterable in the index can be stored but not queried
+ */
+export type VectorMetadata = Record<string, any>
+
+/**
+ * Single vector object for insertion/update
+ * @property key - Unique identifier for the vector
+ * @property data - Vector embedding data
+ * @property metadata - Optional arbitrary metadata
+ */
+export interface VectorObject {
+  key: string
+  data: VectorData
+  metadata?: VectorMetadata
+}
+
+/**
+ * Vector object returned from queries with optional distance
+ * @property key - Unique identifier for the vector
+ * @property data - Vector embedding data (if requested)
+ * @property metadata - Arbitrary metadata (if requested)
+ * @property distance - Similarity distance from query vector (if requested)
+ */
+export interface VectorMatch {
+  key: string
+  data?: VectorData
+  metadata?: VectorMetadata
+  distance?: number
+}
+
+/**
+ * Options for fetching vector buckets
+ * @property prefix - Filter buckets by name prefix
+ * @property maxResults - Maximum number of results to return (default: 100)
+ * @property nextToken - Token for pagination from previous response
+ */
+export interface ListVectorBucketsOptions {
+  prefix?: string
+  maxResults?: number
+  nextToken?: string
+}
+
+/**
+ * Response from listing vector buckets
+ * @property vectorBuckets - Array of bucket names
+ * @property nextToken - Token for fetching next page (if more results exist)
+ */
+export interface ListVectorBucketsResponse {
+  vectorBuckets: { vectorBucketName: string }[]
+  nextToken?: string
+}
+
+/**
+ * Options for listing indexes within a bucket
+ * @property vectorBucketName - Name of the parent vector bucket
+ * @property prefix - Filter indexes by name prefix
+ * @property maxResults - Maximum number of results to return (default: 100)
+ * @property nextToken - Token for pagination from previous response
+ */
+export interface ListIndexesOptions {
+  vectorBucketName: string
+  prefix?: string
+  maxResults?: number
+  nextToken?: string
+}
+
+/**
+ * Response from listing indexes
+ * @property indexes - Array of index names
+ * @property nextToken - Token for fetching next page (if more results exist)
+ */
+export interface ListIndexesResponse {
+  indexes: { indexName: string }[]
+  nextToken?: string
+}
+
+/**
+ * Options for batch reading vectors
+ * @property vectorBucketName - Name of the vector bucket
+ * @property indexName - Name of the index
+ * @property keys - Array of vector keys to retrieve
+ * @property returnData - Whether to include vector data in response
+ * @property returnMetadata - Whether to include metadata in response
+ */
+export interface GetVectorsOptions {
+  vectorBucketName: string
+  indexName: string
+  keys: string[]
+  returnData?: boolean
+  returnMetadata?: boolean
+}
+
+/**
+ * Response from getting vectors
+ * @property vectors - Array of retrieved vector objects
+ */
+export interface GetVectorsResponse {
+  vectors: VectorMatch[]
+}
+
+/**
+ * Options for batch inserting/updating vectors
+ * @property vectorBucketName - Name of the vector bucket
+ * @property indexName - Name of the index
+ * @property vectors - Array of vectors to insert/upsert (1-500 items)
+ */
+export interface PutVectorsOptions {
+  vectorBucketName: string
+  indexName: string
+  vectors: VectorObject[]
+}
+
+/**
+ * Options for batch deleting vectors
+ * @property vectorBucketName - Name of the vector bucket
+ * @property indexName - Name of the index
+ * @property keys - Array of vector keys to delete (1-500 items)
+ */
+export interface DeleteVectorsOptions {
+  vectorBucketName: string
+  indexName: string
+  keys: string[]
+}
+
+/**
+ * Options for listing/scanning vectors in an index
+ * Supports parallel scanning via segment configuration
+ * @property vectorBucketName - Name of the vector bucket
+ * @property indexName - Name of the index
+ * @property maxResults - Maximum number of results to return (default: 500, max: 1000)
+ * @property nextToken - Token for pagination from previous response
+ * @property returnData - Whether to include vector data in response
+ * @property returnMetadata - Whether to include metadata in response
+ * @property segmentCount - Total number of parallel segments (1-16)
+ * @property segmentIndex - Zero-based index of this segment (0 to segmentCount-1)
+ */
+export interface ListVectorsOptions {
+  vectorBucketName: string
+  indexName: string
+  maxResults?: number
+  nextToken?: string
+  returnData?: boolean
+  returnMetadata?: boolean
+  segmentCount?: number
+  segmentIndex?: number
+}
+
+/**
+ * Response from listing vectors
+ * @property vectors - Array of vector objects
+ * @property nextToken - Token for fetching next page (if more results exist)
+ */
+export interface ListVectorsResponse {
+  vectors: VectorMatch[]
+  nextToken?: string
+}
+
+/**
+ * JSON filter expression for metadata filtering
+ * Format and syntax depend on the S3 Vectors service implementation
+ */
+export type VectorFilter = Record<string, any>
+
+/**
+ * Options for querying similar vectors (ANN search)
+ * @property vectorBucketName - Name of the vector bucket
+ * @property indexName - Name of the index
+ * @property queryVector - Query vector to find similar vectors
+ * @property topK - Number of nearest neighbors to return (default: 10)
+ * @property filter - Optional JSON filter for metadata
+ * @property returnDistance - Whether to include distance scores
+ * @property returnMetadata - Whether to include metadata in results
+ */
+export interface QueryVectorsOptions {
+  vectorBucketName: string
+  indexName: string
+  queryVector: VectorData
+  topK?: number
+  filter?: VectorFilter
+  returnDistance?: boolean
+  returnMetadata?: boolean
+}
+
+/**
+ * Response from vector similarity query
+ * @property matches - Array of similar vectors ordered by distance
+ */
+export interface QueryVectorsResponse {
+  matches: VectorMatch[]
+}
+
+/**
+ * Fetch-specific parameters like abort signals
+ * @property signal - AbortSignal for cancelling requests
+ */
+export interface VectorFetchParameters {
+  signal?: AbortSignal
+}
+
+/**
+ * Standard response wrapper for successful operations
+ * @property data - Response data of type T
+ * @property error - Null on success
+ */
+export interface SuccessResponse<T> {
+  data: T
+  error: null
+}
+
+/**
+ * Standard response wrapper for failed operations
+ * @property data - Null on error
+ * @property error - StorageVectorsError with details
+ */
+export interface ErrorResponse {
+  data: null
+  error: StorageVectorsError
+}
+
+/**
+ * Union type for all API responses
+ * Follows the pattern: { data: T, error: null } | { data: null, error: Error }
+ */
+export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.79.1-canary.1'
+export const version = '2.80.0'

package/src/packages/BlobDownloadBuilder.ts

@@ -2,7 +2,10 @@ import { isStorageError } from '../lib/errors'
 import { DownloadResult } from '../lib/types'
 import StreamDownloadBuilder from './StreamDownloadBuilder'
 
-export default class BlobDownloadBuilder implements PromiseLike<DownloadResult<Blob>> {
+export default class BlobDownloadBuilder implements Promise<DownloadResult<Blob>> {
+  readonly [Symbol.toStringTag]: string = 'BlobDownloadBuilder'
+  private promise: Promise<DownloadResult<Blob>> | null = null
+
   constructor(
     private downloadFn: () => Promise<Response>,
     private shouldThrowOnError: boolean
@@ -16,7 +19,24 @@ export default class BlobDownloadBuilder implements PromiseLike<DownloadResult<B
     onfulfilled?: ((value: DownloadResult<Blob>) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
   ): Promise<TResult1 | TResult2> {
-    return this.execute().then(onfulfilled, onrejected)
+    return this.getPromise().then(onfulfilled, onrejected)
+  }
+
+  catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
+  ): Promise<DownloadResult<Blob> | TResult> {
+    return this.getPromise().catch(onrejected)
+  }
+
+  finally(onfinally?: (() => void) | null): Promise<DownloadResult<Blob>> {
+    return this.getPromise().finally(onfinally)
+  }
+
+  private getPromise(): Promise<DownloadResult<Blob>> {
+    if (!this.promise) {
+      this.promise = this.execute()
+    }
+    return this.promise
   }
 
   private async execute(): Promise<DownloadResult<Blob>> {

package/src/packages/StorageAnalyticsApi.ts

@@ -0,0 +1,199 @@
+import { DEFAULT_HEADERS } from '../lib/constants'
+import { isStorageError, StorageError } from '../lib/errors'
+import { Fetch, get, post, remove } from '../lib/fetch'
+import { resolveFetch } from '../lib/helpers'
+import { AnalyticBucket, Bucket } from '../lib/types'
+
+/**
+ * API class for managing Analytics Buckets using Iceberg tables
+ * Provides methods for creating, listing, and deleting analytics buckets
+ */
+export default class StorageAnalyticsApi {
+  protected url: string
+  protected headers: { [key: string]: string }
+  protected fetch: Fetch
+  protected shouldThrowOnError = false
+
+  /**
+   * Creates a new StorageAnalyticsApi instance
+   * @param url - The base URL for the storage API
+   * @param headers - HTTP headers to include in requests
+   * @param fetch - Optional custom fetch implementation
+   */
+  constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
+    this.url = url.replace(/\/$/, '')
+    this.headers = { ...DEFAULT_HEADERS, ...headers }
+    this.fetch = resolveFetch(fetch)
+  }
+
+  /**
+   * Enable throwing errors instead of returning them in the response
+   * When enabled, failed operations will throw instead of returning { data: null, error }
+   *
+   * @returns This instance for method chaining
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
+  /**
+   * Creates a new analytics bucket using Iceberg tables
+   * Analytics buckets are optimized for analytical queries and data processing
+   *
+   * @param name A unique name for the bucket you are creating
+   * @returns Promise with newly created bucket name or error
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await storage.analytics.createBucket('analytics-data')
+   * if (error) {
+   *   console.error('Failed to create analytics bucket:', error.message)
+   * } else {
+   *   console.log('Created bucket:', data.name)
+   * }
+   * ```
+   */
+  async createBucket(name: string): Promise<
+    | {
+        data: AnalyticBucket
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      const data = await post(this.fetch, `${this.url}/bucket`, { name }, { headers: this.headers })
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Retrieves the details of all Analytics Storage buckets within an existing project
+   * Only returns buckets of type 'ANALYTICS'
+   *
+   * @param options Query parameters for listing buckets
+   * @param options.limit Maximum number of buckets to return
+   * @param options.offset Number of buckets to skip
+   * @param options.sortColumn Column to sort by ('id', 'name', 'created_at', 'updated_at')
+   * @param options.sortOrder Sort order ('asc' or 'desc')
+   * @param options.search Search term to filter bucket names
+   * @returns Promise with list of analytics buckets or error
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await storage.analytics.listBuckets({
+   *   limit: 10,
+   *   offset: 0,
+   *   sortColumn: 'created_at',
+   *   sortOrder: 'desc',
+   *   search: 'analytics'
+   * })
+   * if (data) {
+   *   console.log('Found analytics buckets:', data.length)
+   *   data.forEach(bucket => console.log(`- ${bucket.name}`))
+   * }
+   * ```
+   */
+  async listBuckets(options?: {
+    limit?: number
+    offset?: number
+    sortColumn?: 'id' | 'name' | 'created_at' | 'updated_at'
+    sortOrder?: 'asc' | 'desc'
+    search?: string
+  }): Promise<
+    | {
+        data: AnalyticBucket[]
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      // Build query string from options
+      const queryParams = new URLSearchParams()
+      if (options?.limit !== undefined) queryParams.set('limit', options.limit.toString())
+      if (options?.offset !== undefined) queryParams.set('offset', options.offset.toString())
+      if (options?.sortColumn) queryParams.set('sortColumn', options.sortColumn)
+      if (options?.sortOrder) queryParams.set('sortOrder', options.sortOrder)
+      if (options?.search) queryParams.set('search', options.search)
+
+      const queryString = queryParams.toString()
+      const url = queryString ? `${this.url}/bucket?${queryString}` : `${this.url}/bucket`
+
+      const data = await get(this.fetch, url, { headers: this.headers })
+
+      return { data: data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Deletes an existing analytics bucket
+   * A bucket can't be deleted with existing objects inside it
+   * You must first empty the bucket before deletion
+   *
+   * @param bucketId The unique identifier of the bucket you would like to delete
+   * @returns Promise with success message or error
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await analyticsApi.deleteBucket('old-analytics-bucket')
+   * if (error) {
+   *   console.error('Failed to delete bucket:', error.message)
+   * } else {
+   *   console.log('Bucket deleted successfully:', data.message)
+   * }
+   * ```
+   */
+  async deleteBucket(bucketId: string): Promise<
+    | {
+        data: { message: string }
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      const data = await remove(
+        this.fetch,
+        `${this.url}/bucket/${bucketId}`,
+        {},
+        { headers: this.headers }
+      )
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+}

package/src/packages/StorageBucketApi.ts

@@ -2,7 +2,7 @@ import { DEFAULT_HEADERS } from '../lib/constants'
 import { isStorageError, StorageError } from '../lib/errors'
 import { Fetch, get, post, put, remove } from '../lib/fetch'
 import { resolveFetch } from '../lib/helpers'
-import { Bucket, BucketType } from '../lib/types'
+import { Bucket, BucketType, ListBucketOptions } from '../lib/types'
 import { StorageClientOptions } from '../StorageClient'
 
 export default class StorageBucketApi {
@@ -28,7 +28,7 @@ export default class StorageBucketApi {
       }
     }
 
-    this.url = baseUrl.href
+    this.url = baseUrl.href.replace(/\/$/, '')
     this.headers = { ...DEFAULT_HEADERS, ...headers }
     this.fetch = resolveFetch(fetch)
   }
@@ -44,7 +44,7 @@ export default class StorageBucketApi {
   /**
    * Retrieves the details of all Storage buckets within an existing project.
    */
-  async listBuckets(): Promise<
+  async listBuckets(options?: ListBucketOptions): Promise<
     | {
         data: Bucket[]
         error: null
@@ -55,7 +55,10 @@ export default class StorageBucketApi {
       }
   > {
     try {
-      const data = await get(this.fetch, `${this.url}/bucket`, { headers: this.headers })
+      const queryString = this.listBucketOptionsToQueryString(options)
+      const data = await get(this.fetch, `${this.url}/bucket${queryString}`, {
+        headers: this.headers,
+      })
       return { data, error: null }
     } catch (error) {
       if (this.shouldThrowOnError) {
@@ -286,4 +289,26 @@ export default class StorageBucketApi {
       throw error
     }
   }
+
+  private listBucketOptionsToQueryString(options?: ListBucketOptions): string {
+    const params: Record<string, string> = {}
+    if (options) {
+      if ('limit' in options) {
+        params.limit = String(options.limit)
+      }
+      if ('offset' in options) {
+        params.offset = String(options.offset)
+      }
+      if (options.search) {
+        params.search = options.search
+      }
+      if (options.sortColumn) {
+        params.sortColumn = options.sortColumn
+      }
+      if (options.sortOrder) {
+        params.sortOrder = options.sortOrder
+      }
+    }
+    return Object.keys(params).length > 0 ? '?' + new URLSearchParams(params).toString() : ''
+  }
 }

package/src/packages/StorageFileApi.ts

@@ -110,8 +110,11 @@ export default class StorageFileApi {
         body.append('', fileBody)
       } else if (typeof FormData !== 'undefined' && fileBody instanceof FormData) {
         body = fileBody
-        body.append('cacheControl', options.cacheControl as string)
-        if (metadata) {
+        // Only append if not already present
+        if (!body.has('cacheControl')) {
+          body.append('cacheControl', options.cacheControl as string)
+        }
+        if (metadata && !body.has('metadata')) {
           body.append('metadata', this.encodeMetadata(metadata))
         }
       } else {
@@ -122,6 +125,16 @@ export default class StorageFileApi {
         if (metadata) {
           headers['x-metadata'] = this.toBase64(this.encodeMetadata(metadata))
         }
+
+        // Node.js streams require duplex option for fetch in Node 20+
+        // Check for both web ReadableStream and Node.js streams
+        const isStream =
+          (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) ||
+          (body && typeof body === 'object' && 'pipe' in body && typeof body.pipe === 'function')
+
+        if (isStream && !options.duplex) {
+          options.duplex = 'half'
+        }
       }
 
       if (fileOptions?.headers) {