@supabase/storage-js 2.75.1 → 2.75.2-canary.1

package/src/lib/vectors/fetch.ts

@@ -0,0 +1,218 @@
+import { StorageVectorsApiError, StorageVectorsUnknownError } from './errors'
+import { isPlainObject, resolveResponse } from './helpers'
+import { VectorFetchParameters } from './types'
+
+export type Fetch = typeof fetch
+
+/**
+ * Options for fetch requests
+ * @property headers - Custom HTTP headers
+ * @property noResolveJson - If true, return raw Response instead of parsing JSON
+ */
+export interface FetchOptions {
+  headers?: {
+    [key: string]: string
+  }
+  noResolveJson?: boolean
+}
+
+/**
+ * HTTP methods supported by the API
+ */
+export type RequestMethodType = 'GET' | 'POST' | 'PUT' | 'DELETE'
+
+/**
+ * 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 || err.error || JSON.stringify(err)
+
+/**
+ * Handles fetch errors and converts them to StorageVectors error types
+ * @param error - The error caught from fetch
+ * @param reject - Promise rejection function
+ * @param options - Fetch options that may affect error handling
+ */
+const handleError = async (
+  error: unknown,
+  reject: (reason?: any) => void,
+  options?: FetchOptions
+) => {
+  // 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 status = (error as any).status || 500
+    const responseError = error as any
+
+    // 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 StorageVectorsApiError(_getErrorMessage(err), status, statusCode))
+        })
+        .catch(() => {
+          // If JSON parsing fails, create an ApiError with the HTTP status code
+          const statusCode = status + ''
+          const message = responseError.statusText || `HTTP ${status} error`
+          reject(new StorageVectorsApiError(message, status, statusCode))
+        })
+    } else {
+      // No json() method available, create error from status
+      const statusCode = status + ''
+      const message = responseError.statusText || `HTTP ${status} error`
+      reject(new StorageVectorsApiError(message, status, statusCode))
+    }
+  } else {
+    reject(new StorageVectorsUnknownError(_getErrorMessage(error), error))
+  }
+}
+
+/**
+ * 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?: VectorFetchParameters,
+  body?: object
+) => {
+  const params: { [k: string]: any } = { method, headers: options?.headers || {} }
+
+  if (method === 'GET' || !body) {
+    return params
+  }
+
+  if (isPlainObject(body)) {
+    params.headers = { 'Content-Type': 'application/json', ...options?.headers }
+    params.body = JSON.stringify(body)
+  } else {
+    params.body = body
+  }
+
+  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
+ * @returns Promise with parsed response or error
+ */
+async function _handleRequest(
+  fetcher: Fetch,
+  method: RequestMethodType,
+  url: string,
+  options?: FetchOptions,
+  parameters?: VectorFetchParameters,
+  body?: object
+): 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)
+        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))
+  })
+}
+
+/**
+ * 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
+ */
+export async function get(
+  fetcher: Fetch,
+  url: string,
+  options?: FetchOptions,
+  parameters?: VectorFetchParameters
+): Promise<any> {
+  return _handleRequest(fetcher, 'GET', url, options, parameters)
+}
+
+/**
+ * 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
+ */
+export async function post(
+  fetcher: Fetch,
+  url: string,
+  body: object,
+  options?: FetchOptions,
+  parameters?: VectorFetchParameters
+): Promise<any> {
+  return _handleRequest(fetcher, 'POST', url, options, parameters, body)
+}
+
+/**
+ * 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
+ */
+export async function put(
+  fetcher: Fetch,
+  url: string,
+  body: object,
+  options?: FetchOptions,
+  parameters?: VectorFetchParameters
+): Promise<any> {
+  return _handleRequest(fetcher, 'PUT', url, options, parameters, body)
+}
+
+/**
+ * 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
+ */
+export async function remove(
+  fetcher: Fetch,
+  url: string,
+  body: object,
+  options?: FetchOptions,
+  parameters?: VectorFetchParameters
+): Promise<any> {
+  return _handleRequest(fetcher, 'DELETE', url, options, parameters, body)
+}

package/src/lib/vectors/helpers.ts

@@ -0,0 +1,93 @@
+type Fetch = typeof fetch
+
+/**
+ * Resolves the fetch implementation to use
+ * Uses custom fetch if provided, otherwise falls back to:
+ * - Native fetch in browser/modern environments
+ * - @supabase/node-fetch polyfill in Node.js environments without fetch
+ *
+ * @param customFetch - Optional custom fetch implementation
+ * @returns Resolved fetch function
+ */
+export const resolveFetch = (customFetch?: Fetch): Fetch => {
+  let _fetch: Fetch
+  if (customFetch) {
+    _fetch = customFetch
+  } else if (typeof fetch === 'undefined') {
+    _fetch = (...args) =>
+      import('@supabase/node-fetch' as any).then(({ default: fetch }) => fetch(...args))
+  } else {
+    _fetch = fetch
+  }
+  return (...args) => _fetch(...args)
+}
+
+/**
+ * Resolves the Response constructor to use
+ * Uses native Response in browser/modern environments
+ * Falls back to @supabase/node-fetch polyfill in Node.js environments
+ *
+ * @returns Response constructor
+ */
+export const resolveResponse = async (): Promise<typeof Response> => {
+  if (typeof Response === 'undefined') {
+    // @ts-ignore
+    return (await import('@supabase/node-fetch' as any)).Response
+  }
+
+  return Response
+}
+
+/**
+ * Determine if input is a plain object
+ * An object is plain if it's created by either {}, new Object(), or Object.create(null)
+ *
+ * @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) {
+    return false
+  }
+
+  const prototype = Object.getPrototypeOf(value)
+  return (
+    (prototype === null ||
+      prototype === Object.prototype ||
+      Object.getPrototypeOf(prototype) === null) &&
+    !(Symbol.toStringTag in value) &&
+    !(Symbol.iterator in value)
+  )
+}
+
+/**
+ * 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/vectors/index.ts

@@ -0,0 +1,66 @@
+// Main client
+export { StorageVectorsClient, VectorBucketScope, VectorIndexScope } from './StorageVectorsClient'
+export type { StorageVectorsClientOptions } from './StorageVectorsClient'
+
+// API classes (for advanced usage)
+export { default as VectorBucketApi } from './VectorBucketApi'
+export { default as VectorIndexApi } from './VectorIndexApi'
+export { default as VectorDataApi } from './VectorDataApi'
+export type { CreateIndexOptions } from './VectorIndexApi'
+
+// Types
+export type {
+  // Core types
+  VectorBucket,
+  VectorIndex,
+  VectorData,
+  VectorMetadata,
+  VectorObject,
+  VectorMatch,
+  EncryptionConfiguration,
+  MetadataConfiguration,
+  VectorDataType,
+  DistanceMetric,
+  VectorFilter,
+
+  // Request/Response types
+  ListVectorBucketsOptions,
+  ListVectorBucketsResponse,
+  ListIndexesOptions,
+  ListIndexesResponse,
+  PutVectorsOptions,
+  GetVectorsOptions,
+  GetVectorsResponse,
+  DeleteVectorsOptions,
+  ListVectorsOptions,
+  ListVectorsResponse,
+  QueryVectorsOptions,
+  QueryVectorsResponse,
+
+  // Response wrappers
+  ApiResponse,
+  SuccessResponse,
+  ErrorResponse,
+  VectorFetchParameters,
+} from './types'
+
+// Errors
+export {
+  StorageVectorsError,
+  StorageVectorsApiError,
+  StorageVectorsUnknownError,
+  StorageVectorsErrorCode,
+  isStorageVectorsError,
+} from './errors'
+
+// Fetch utilities (for custom implementations)
+export type { Fetch, FetchOptions, RequestMethodType } from './fetch'
+
+// Helper utilities
+export {
+  resolveFetch,
+  resolveResponse,
+  isPlainObject,
+  normalizeToFloat32,
+  validateVectorDimension,
+} from './helpers'

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.75.1'
+export const version = '2.75.2-canary.1'