@supabase/storage-js 2.91.1 → 2.91.2

package/src/lib/common/fetch.ts

@@ -0,0 +1,286 @@
+import { StorageApiError, StorageUnknownError, ErrorNamespace } from './errors'
+import { isPlainObject, resolveResponse } from './helpers'
+
+export type Fetch = typeof fetch
+
+/**
+ * Options for fetch requests
+ */
+export interface FetchOptions {
+  headers?: {
+    [key: string]: string
+  }
+  duplex?: string
+  noResolveJson?: boolean
+}
+
+/**
+ * Additional fetch parameters (e.g., signal for cancellation)
+ */
+export interface FetchParameters {
+  signal?: AbortSignal
+}
+
+/**
+ * HTTP methods supported by the API
+ */
+export type RequestMethodType = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD'
+
+/**
+ * Extracts error message from various error response formats
+ * @param err - Error object from API
+ * @returns Human-readable error message
+ */
+const _getErrorMessage = (err: any): string =>
+  err.msg ||
+  err.message ||
+  err.error_description ||
+  (typeof err.error === 'string' ? err.error : err.error?.message) ||
+  JSON.stringify(err)
+
+/**
+ * Handles fetch errors and converts them to Storage error types
+ * @param error - The error caught from fetch
+ * @param reject - Promise rejection function
+ * @param options - Fetch options that may affect error handling
+ * @param namespace - Error namespace ('storage' or 'vectors')
+ */
+const handleError = async (
+  error: unknown,
+  reject: (reason?: any) => void,
+  options: FetchOptions | undefined,
+  namespace: ErrorNamespace
+) => {
+  // Check if error is a Response-like object (has status and ok properties)
+  // This is more reliable than instanceof which can fail across realms
+  const isResponseLike =
+    error &&
+    typeof error === 'object' &&
+    'status' in error &&
+    'ok' in error &&
+    typeof (error as any).status === 'number'
+
+  if (isResponseLike && !options?.noResolveJson) {
+    const responseError = error as any
+    const status = responseError.status || 500
+
+    // Try to parse JSON body if available
+    if (typeof responseError.json === 'function') {
+      responseError
+        .json()
+        .then((err: any) => {
+          const statusCode = err?.statusCode || err?.code || status + ''
+          reject(new StorageApiError(_getErrorMessage(err), status, statusCode, namespace))
+        })
+        .catch(() => {
+          // If JSON parsing fails for vectors, create ApiError with HTTP status
+          if (namespace === 'vectors') {
+            const statusCode = status + ''
+            const message = responseError.statusText || `HTTP ${status} error`
+            reject(new StorageApiError(message, status, statusCode, namespace))
+          } else {
+            const statusCode = status + ''
+            const message = responseError.statusText || `HTTP ${status} error`
+            reject(new StorageApiError(message, status, statusCode, namespace))
+          }
+        })
+    } else {
+      // No json() method available, create error from status
+      const statusCode = status + ''
+      const message = responseError.statusText || `HTTP ${status} error`
+      reject(new StorageApiError(message, status, statusCode, namespace))
+    }
+  } else {
+    reject(new StorageUnknownError(_getErrorMessage(error), error, namespace))
+  }
+}
+
+/**
+ * Builds request parameters for fetch calls
+ * @param method - HTTP method
+ * @param options - Custom fetch options
+ * @param parameters - Additional fetch parameters like AbortSignal
+ * @param body - Request body (will be JSON stringified if plain object)
+ * @returns Complete fetch request parameters
+ */
+const _getRequestParams = (
+  method: RequestMethodType,
+  options?: FetchOptions,
+  parameters?: FetchParameters,
+  body?: object
+) => {
+  const params: { [k: string]: any } = { method, headers: options?.headers || {} }
+
+  if (method === 'GET' || method === 'HEAD' || !body) {
+    return { ...params, ...parameters }
+  }
+
+  if (isPlainObject(body)) {
+    params.headers = { 'Content-Type': 'application/json', ...options?.headers }
+    params.body = JSON.stringify(body)
+  } else {
+    params.body = body
+  }
+
+  if (options?.duplex) {
+    params.duplex = options.duplex
+  }
+
+  return { ...params, ...parameters }
+}
+
+/**
+ * Internal request handler that wraps fetch with error handling
+ * @param fetcher - Fetch function to use
+ * @param method - HTTP method
+ * @param url - Request URL
+ * @param options - Custom fetch options
+ * @param parameters - Additional fetch parameters
+ * @param body - Request body
+ * @param namespace - Error namespace ('storage' or 'vectors')
+ * @returns Promise with parsed response or error
+ */
+async function _handleRequest(
+  fetcher: Fetch,
+  method: RequestMethodType,
+  url: string,
+  options: FetchOptions | undefined,
+  parameters: FetchParameters | undefined,
+  body: object | undefined,
+  namespace: ErrorNamespace
+): Promise<any> {
+  return new Promise((resolve, reject) => {
+    fetcher(url, _getRequestParams(method, options, parameters, body))
+      .then((result) => {
+        if (!result.ok) throw result
+        if (options?.noResolveJson) return result
+
+        // Handle empty responses (204, empty body) - especially for vectors
+        if (namespace === 'vectors') {
+          const contentType = result.headers.get('content-type')
+          if (!contentType || !contentType.includes('application/json')) {
+            return {}
+          }
+        }
+
+        return result.json()
+      })
+      .then((data) => resolve(data))
+      .catch((error) => handleError(error, reject, options, namespace))
+  })
+}
+
+/**
+ * Creates a fetch API with the specified namespace
+ * @param namespace - Error namespace ('storage' or 'vectors')
+ * @returns Object with HTTP method functions
+ */
+export function createFetchApi(namespace: ErrorNamespace = 'storage') {
+  return {
+    /**
+     * Performs a GET request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with parsed response
+     */
+    get: async (
+      fetcher: Fetch,
+      url: string,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(fetcher, 'GET', url, options, parameters, undefined, namespace)
+    },
+
+    /**
+     * Performs a POST request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param body - Request body to be JSON stringified
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with parsed response
+     */
+    post: async (
+      fetcher: Fetch,
+      url: string,
+      body: object,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(fetcher, 'POST', url, options, parameters, body, namespace)
+    },
+
+    /**
+     * Performs a PUT request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param body - Request body to be JSON stringified
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with parsed response
+     */
+    put: async (
+      fetcher: Fetch,
+      url: string,
+      body: object,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(fetcher, 'PUT', url, options, parameters, body, namespace)
+    },
+
+    /**
+     * Performs a HEAD request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with Response object (not JSON parsed)
+     */
+    head: async (
+      fetcher: Fetch,
+      url: string,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(
+        fetcher,
+        'HEAD',
+        url,
+        {
+          ...options,
+          noResolveJson: true,
+        },
+        parameters,
+        undefined,
+        namespace
+      )
+    },
+
+    /**
+     * Performs a DELETE request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param body - Request body to be JSON stringified
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with parsed response
+     */
+    remove: async (
+      fetcher: Fetch,
+      url: string,
+      body: object,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(fetcher, 'DELETE', url, options, parameters, body, namespace)
+    },
+  }
+}
+
+// Default exports for backward compatibility with 'storage' namespace
+const defaultApi = createFetchApi('storage')
+export const { get, post, put, head, remove } = defaultApi

package/src/lib/{helpers.ts → common/helpers.ts}

@@ -1,5 +1,12 @@
 type Fetch = typeof fetch
 
+/**
+ * Resolves the fetch implementation to use
+ * Uses custom fetch if provided, otherwise uses native fetch
+ *
+ * @param customFetch - Optional custom fetch implementation
+ * @returns Resolved fetch function
+ */
 export const resolveFetch = (customFetch?: Fetch): Fetch => {
   if (customFetch) {
     return (...args) => customFetch(...args)
@@ -7,30 +14,23 @@ export const resolveFetch = (customFetch?: Fetch): Fetch => {
   return (...args) => fetch(...args)
 }
 
+/**
+ * Resolves the Response constructor to use
+ * Returns native Response constructor
+ *
+ * @returns Response constructor
+ */
 export const resolveResponse = (): typeof Response => {
   return Response
 }
 
-export const recursiveToCamel = (item: Record<string, any>): unknown => {
-  if (Array.isArray(item)) {
-    return item.map((el) => recursiveToCamel(el))
-  } else if (typeof item === 'function' || item !== Object(item)) {
-    return item
-  }
-
-  const result: Record<string, any> = {}
-  Object.entries(item).forEach(([key, value]) => {
-    const newKey = key.replace(/([-_][a-z])/gi, (c) => c.toUpperCase().replace(/[-_]/g, ''))
-    result[newKey] = recursiveToCamel(value)
-  })
-
-  return result
-}
-
 /**
  * Determine if input is a plain object
  * An object is plain if it's created by either {}, new Object(), or Object.create(null)
- * source: https://github.com/sindresorhus/is-plain-obj
+ *
+ * @param value - Value to check
+ * @returns True if value is a plain object
+ * @source https://github.com/sindresorhus/is-plain-obj
  */
 export const isPlainObject = (value: object): boolean => {
   if (typeof value !== 'object' || value === null) {
@@ -47,6 +47,29 @@ export const isPlainObject = (value: object): boolean => {
   )
 }
 
+/**
+ * Recursively converts object keys from snake_case to camelCase
+ * Used for normalizing API responses
+ *
+ * @param item - Object to convert
+ * @returns Converted object with camelCase keys
+ */
+export const recursiveToCamel = (item: Record<string, any>): unknown => {
+  if (Array.isArray(item)) {
+    return item.map((el) => recursiveToCamel(el))
+  } else if (typeof item === 'function' || item !== Object(item)) {
+    return item
+  }
+
+  const result: Record<string, any> = {}
+  Object.entries(item).forEach(([key, value]) => {
+    const newKey = key.replace(/([-_][a-z])/gi, (c) => c.toUpperCase().replace(/[-_]/g, ''))
+    result[newKey] = recursiveToCamel(value)
+  })
+
+  return result
+}
+
 /**
  * Validates if a given bucket name is valid according to Supabase Storage API rules
  * Mirrors backend validation from: storage/src/storage/limits.ts:isValidBucketName()
@@ -90,3 +113,34 @@ export const isValidBucketName = (bucketName: string): boolean => {
   const bucketNameRegex = /^[\w!.\*'() &$@=;:+,?-]+$/
   return bucketNameRegex.test(bucketName)
 }
+
+/**
+ * Normalizes a number array to float32 format
+ * Ensures all vector values are valid 32-bit floats
+ *
+ * @param values - Array of numbers to normalize
+ * @returns Normalized float32 array
+ */
+export const normalizeToFloat32 = (values: number[]): number[] => {
+  // Use Float32Array to ensure proper precision
+  return Array.from(new Float32Array(values))
+}
+
+/**
+ * Validates vector dimensions match expected dimension
+ * Throws error if dimensions don't match
+ *
+ * @param vector - Vector data to validate
+ * @param expectedDimension - Expected vector dimension
+ * @throws Error if dimensions don't match
+ */
+export const validateVectorDimension = (
+  vector: { float32: number[] },
+  expectedDimension?: number
+): void => {
+  if (expectedDimension !== undefined && vector.float32.length !== expectedDimension) {
+    throw new Error(
+      `Vector dimension mismatch: expected ${expectedDimension}, got ${vector.float32.length}`
+    )
+  }
+}

package/src/lib/types.ts

@@ -1,4 +1,4 @@
-import { StorageError } from './errors'
+import { StorageError } from './common/errors'
 
 /**
  * Type of storage bucket
@@ -257,3 +257,306 @@ export type DownloadResult<T> =
       data: null
       error: StorageError
     }
+// ============================================================================
+// VECTOR STORAGE TYPES
+// ============================================================================
+
+/**
+ * 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 vectors - Array of similar vectors ordered by distance
+ * @property distanceMetric - The distance metric used for the similarity search
+ */
+export interface QueryVectorsResponse {
+  vectors: VectorMatch[]
+  distanceMetric?: DistanceMetric
+}
+
+/**
+ * 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 - StorageError with details (named StorageVectorsError for vector operations)
+ */
+export interface ErrorResponse {
+  data: null
+  error: StorageError
+}
+
+/**
+ * Union type for all API responses
+ * Follows the pattern: { data: T, error: null } | { data: null, error: Error }
+ */
+export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse