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

package/src/lib/vectors/VectorIndexApi.ts

@@ -0,0 +1,245 @@
+import { DEFAULT_HEADERS } from './constants'
+import { isStorageVectorsError } from './errors'
+import { Fetch, post } from './fetch'
+import { resolveFetch } from './helpers'
+import {
+  ApiResponse,
+  VectorIndex,
+  ListIndexesOptions,
+  ListIndexesResponse,
+  VectorDataType,
+  DistanceMetric,
+  MetadataConfiguration,
+} from './types'
+
+/**
+ * Options for creating a vector index
+ */
+export interface CreateIndexOptions {
+  vectorBucketName: string
+  indexName: string
+  dataType: VectorDataType
+  dimension: number
+  distanceMetric: DistanceMetric
+  metadataConfiguration?: MetadataConfiguration
+}
+
+/**
+ * API class for managing Vector Indexes within Vector Buckets
+ * Provides methods for creating, reading, listing, and deleting vector indexes
+ */
+export default class VectorIndexApi {
+  protected url: string
+  protected headers: { [key: string]: string }
+  protected fetch: Fetch
+  protected shouldThrowOnError = false
+
+  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
+   * @example
+   * ```typescript
+   * const client = new VectorIndexApi(url, headers)
+   * client.throwOnError()
+   * const { data } = await client.createIndex(options) // throws on error
+   * ```
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
+  /**
+   * Creates a new vector index within a bucket
+   * Defines the schema for vectors including dimensionality, distance metric, and metadata config
+   *
+   * @param options - Index configuration
+   * @param options.vectorBucketName - Name of the parent vector bucket
+   * @param options.indexName - Unique name for the index within the bucket
+   * @param options.dataType - Data type for vector components (currently only 'float32')
+   * @param options.dimension - Dimensionality of vectors (e.g., 384, 768, 1536)
+   * @param options.distanceMetric - Similarity metric ('cosine', 'euclidean', 'dotproduct')
+   * @param options.metadataConfiguration - Optional config for non-filterable metadata keys
+   * @returns Promise with empty response on success or error
+   *
+   * @throws {StorageVectorsApiError} With code:
+   * - `S3VectorConflictException` if index already exists (HTTP 409)
+   * - `S3VectorMaxIndexesExceeded` if quota exceeded (HTTP 400)
+   * - `S3VectorNotFoundException` if bucket doesn't exist (HTTP 404)
+   * - `InternalError` for server errors (HTTP 500)
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await client.createIndex({
+   *   vectorBucketName: 'embeddings-prod',
+   *   indexName: 'documents-openai-small',
+   *   dataType: 'float32',
+   *   dimension: 1536,
+   *   distanceMetric: 'cosine',
+   *   metadataConfiguration: {
+   *     nonFilterableMetadataKeys: ['raw_text', 'internal_id']
+   *   }
+   * })
+   * ```
+   */
+  async createIndex(options: CreateIndexOptions): Promise<ApiResponse<undefined>> {
+    try {
+      const data = await post(this.fetch, `${this.url}/CreateIndex`, options, {
+        headers: this.headers,
+      })
+      return { data: data || {}, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Retrieves metadata for a specific vector index
+   * Returns index configuration including dimension, distance metric, and metadata settings
+   *
+   * @param vectorBucketName - Name of the parent vector bucket
+   * @param indexName - Name of the index to retrieve
+   * @returns Promise with index metadata or error
+   *
+   * @throws {StorageVectorsApiError} With code:
+   * - `S3VectorNotFoundException` if index or bucket doesn't exist (HTTP 404)
+   * - `InternalError` for server errors (HTTP 500)
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await client.getIndex('embeddings-prod', 'documents-openai-small')
+   * if (data) {
+   *   console.log('Index dimension:', data.index.dimension)
+   *   console.log('Distance metric:', data.index.distanceMetric)
+   * }
+   * ```
+   */
+  async getIndex(
+    vectorBucketName: string,
+    indexName: string
+  ): Promise<ApiResponse<{ index: VectorIndex }>> {
+    try {
+      const data = await post(
+        this.fetch,
+        `${this.url}/GetIndex`,
+        { vectorBucketName, indexName },
+        { headers: this.headers }
+      )
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Lists vector indexes within a bucket with optional filtering and pagination
+   * Supports prefix-based filtering and paginated results
+   *
+   * @param options - Listing options
+   * @param options.vectorBucketName - Name of the parent vector bucket
+   * @param options.prefix - Filter indexes by name prefix
+   * @param options.maxResults - Maximum results per page (default: 100)
+   * @param options.nextToken - Pagination token from previous response
+   * @returns Promise with list of indexes and pagination token
+   *
+   * @throws {StorageVectorsApiError} With code:
+   * - `S3VectorNotFoundException` if bucket doesn't exist (HTTP 404)
+   * - `InternalError` for server errors (HTTP 500)
+   *
+   * @example
+   * ```typescript
+   * // List all indexes in a bucket
+   * const { data, error } = await client.listIndexes({
+   *   vectorBucketName: 'embeddings-prod',
+   *   prefix: 'documents-'
+   * })
+   * if (data) {
+   *   console.log('Found indexes:', data.indexes.map(i => i.indexName))
+   *   // Fetch next page if available
+   *   if (data.nextToken) {
+   *     const next = await client.listIndexes({
+   *       vectorBucketName: 'embeddings-prod',
+   *       nextToken: data.nextToken
+   *     })
+   *   }
+   * }
+   * ```
+   */
+  async listIndexes(options: ListIndexesOptions): Promise<ApiResponse<ListIndexesResponse>> {
+    try {
+      const data = await post(this.fetch, `${this.url}/ListIndexes`, options, {
+        headers: this.headers,
+      })
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Deletes a vector index and all its data
+   * This operation removes the index schema and all vectors stored in the index
+   *
+   * @param vectorBucketName - Name of the parent vector bucket
+   * @param indexName - Name of the index to delete
+   * @returns Promise with empty response on success or error
+   *
+   * @throws {StorageVectorsApiError} With code:
+   * - `S3VectorNotFoundException` if index or bucket doesn't exist (HTTP 404)
+   * - `InternalError` for server errors (HTTP 500)
+   *
+   * @example
+   * ```typescript
+   * // Delete an index and all its vectors
+   * const { error } = await client.deleteIndex('embeddings-prod', 'old-index')
+   * if (!error) {
+   *   console.log('Index deleted successfully')
+   * }
+   * ```
+   */
+  async deleteIndex(vectorBucketName: string, indexName: string): Promise<ApiResponse<undefined>> {
+    try {
+      const data = await post(
+        this.fetch,
+        `${this.url}/DeleteIndex`,
+        { vectorBucketName, indexName },
+        { headers: this.headers }
+      )
+      return { data: data || {}, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+}

package/src/lib/vectors/constants.ts

@@ -0,0 +1,5 @@
+import { version } from '../version'
+export const DEFAULT_HEADERS = {
+  'X-Client-Info': `storage-js/${version}`,
+  'Content-Type': 'application/json',
+}

package/src/lib/vectors/errors.ts

@@ -0,0 +1,78 @@
+/**
+ * Base error class for all Storage Vectors errors
+ */
+export class StorageVectorsError extends Error {
+  protected __isStorageVectorsError = true
+
+  constructor(message: string) {
+    super(message)
+    this.name = 'StorageVectorsError'
+  }
+}
+
+/**
+ * Type guard to check if an error is a StorageVectorsError
+ * @param error - The error to check
+ * @returns True if the error is a StorageVectorsError
+ */
+export function isStorageVectorsError(error: unknown): error is StorageVectorsError {
+  return typeof error === 'object' && error !== null && '__isStorageVectorsError' in error
+}
+
+/**
+ * API error returned from S3 Vectors service
+ * Includes HTTP status code and service-specific error code
+ */
+export class StorageVectorsApiError extends StorageVectorsError {
+  status: number
+  statusCode: string
+
+  constructor(message: string, status: number, statusCode: string) {
+    super(message)
+    this.name = 'StorageVectorsApiError'
+    this.status = status
+    this.statusCode = statusCode
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      statusCode: this.statusCode,
+    }
+  }
+}
+
+/**
+ * Unknown error that doesn't match expected error patterns
+ * Wraps the original error for debugging
+ */
+export class StorageVectorsUnknownError extends StorageVectorsError {
+  originalError: unknown
+
+  constructor(message: string, originalError: unknown) {
+    super(message)
+    this.name = 'StorageVectorsUnknownError'
+    this.originalError = originalError
+  }
+}
+
+/**
+ * Error codes specific to S3 Vectors API
+ * Maps AWS service errors to application-friendly error codes
+ */
+export enum StorageVectorsErrorCode {
+  /** Internal server fault (HTTP 500) */
+  InternalError = 'InternalError',
+  /** Resource already exists / conflict (HTTP 409) */
+  S3VectorConflictException = 'S3VectorConflictException',
+  /** Resource not found (HTTP 404) */
+  S3VectorNotFoundException = 'S3VectorNotFoundException',
+  /** Delete bucket while not empty (HTTP 400) */
+  S3VectorBucketNotEmpty = 'S3VectorBucketNotEmpty',
+  /** Exceeds bucket quota/limit (HTTP 400) */
+  S3VectorMaxBucketsExceeded = 'S3VectorMaxBucketsExceeded',
+  /** Exceeds index quota/limit (HTTP 400) */
+  S3VectorMaxIndexesExceeded = 'S3VectorMaxIndexesExceeded',
+}

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,79 @@
+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)
+  }
+  return (...args) => fetch(...args)
+}
+
+/**
+ * Resolves the Response constructor to use
+ * Returns native Response constructor
+ *
+ * @returns Response constructor
+ */
+export const resolveResponse = (): typeof 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'