@edgestore/shared 0.0.0-canary-20260730114359

package/src/internals/providerCapabilities.ts

@@ -0,0 +1,126 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type {
+  BackendFile,
+  GetSignedUrlRes,
+  ProviderFileMutationResult,
+} from './providerTypes';
+
+export type ProviderCapabilityName =
+  | 'upload'
+  | 'get'
+  | 'list'
+  | 'confirm'
+  | 'delete'
+  | 'restore'
+  | 'getSignedUrls';
+
+export type ProviderCapability<
+  TProvider,
+  TName extends ProviderCapabilityName,
+> = TName extends 'upload'
+  ? TProvider extends { uploads: { upload: infer TOperation } }
+    ? Extract<TOperation, (...args: never[]) => unknown>
+    : never
+  : TProvider extends {
+        files: infer TFiles;
+      }
+    ? TName extends keyof TFiles
+      ? Extract<TFiles[TName], (...args: never[]) => unknown>
+      : never
+    : never;
+
+export type ProviderCapabilityInput<
+  TProvider,
+  TName extends ProviderCapabilityName,
+> = Parameters<ProviderCapability<TProvider, TName>>[0];
+
+export type ProviderCapabilityResult<
+  TProvider,
+  TName extends ProviderCapabilityName,
+> = Awaited<ReturnType<ProviderCapability<TProvider, TName>>>;
+
+type ProviderReferenceSchema<TProvider> = TProvider extends {
+  reference: {
+    schema: infer TSchema extends StandardSchemaV1;
+  };
+}
+  ? TSchema
+  : never;
+
+export type ProviderReferenceInput<TProvider> = StandardSchemaV1.InferInput<
+  ProviderReferenceSchema<TProvider>
+>;
+
+export type ProviderReference<TProvider> = StandardSchemaV1.InferOutput<
+  ProviderReferenceSchema<TProvider>
+>;
+
+export type ProviderCursor<TProvider> = TProvider extends {
+  files: {
+    cursorSchema: infer TSchema extends StandardSchemaV1;
+  };
+}
+  ? StandardSchemaV1.InferOutput<TSchema>
+  : string;
+
+export type ProviderCapabilityFile<
+  TProvider,
+  TName extends 'upload' | 'get' | 'list',
+> = TName extends 'upload'
+  ? ProviderCapabilityResult<TProvider, TName> extends {
+      file: infer TFile extends BackendFile;
+    }
+    ? TFile
+    : never
+  : TName extends 'list'
+    ? ProviderCapabilityResult<TProvider, TName> extends {
+        items: (infer TFile extends BackendFile)[];
+      }
+      ? TFile
+      : never
+    : ProviderCapabilityResult<TProvider, TName> extends BackendFile
+      ? ProviderCapabilityResult<TProvider, TName>
+      : never;
+
+export type ProviderMutationItem<
+  TProvider,
+  TName extends 'confirm' | 'delete' | 'restore',
+> =
+  ProviderCapabilityResult<TProvider, TName> extends {
+    results: (infer TItem)[];
+  }
+    ? TItem
+    : never;
+
+export type ProviderMutationError<
+  TProvider,
+  TName extends 'confirm' | 'delete' | 'restore',
+> =
+  Extract<ProviderMutationItem<TProvider, TName>, { success: false }> extends {
+    error: infer TError;
+  }
+    ? TError
+    : never;
+
+type ProviderMutationErrorCode<
+  TProvider,
+  TName extends 'confirm' | 'delete' | 'restore',
+> =
+  ProviderMutationError<TProvider, TName> extends {
+    code: infer TErrorCode extends string;
+  }
+    ? TErrorCode
+    : never;
+
+export type ProviderSignedUrlResult<TProvider> =
+  ProviderCapabilityResult<
+    TProvider,
+    'getSignedUrls'
+  > extends (infer TResult extends GetSignedUrlRes)[]
+    ? TResult
+    : never;
+
+export type ProviderMutationResult<
+  TProvider,
+  TName extends 'confirm' | 'delete' | 'restore',
+> = ProviderFileMutationResult<ProviderMutationErrorCode<TProvider, TName>>;

package/src/internals/providerTypes.ts

@@ -0,0 +1,388 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { type MaybePromise } from '../types';
+import {
+  type AnyContext,
+  type AnyMetadata,
+  type EdgeStoreRouter,
+} from './bucketBuilder';
+
+export type InitParams<TCtx extends AnyContext = AnyContext> = {
+  ctx: TCtx;
+  router: EdgeStoreRouter<TCtx>;
+};
+
+export type ClientInit = {
+  path: string;
+  headers?: Record<string, string>;
+};
+
+export type InitRes = {
+  token?: string;
+  clientInit?: ClientInit;
+};
+
+export type RequestUploadParams = {
+  multipart?: {
+    uploadId?: string;
+    parts: number[];
+  };
+  bucketName: string;
+  bucketType: string;
+  fileInfo: {
+    type?: string;
+    size: number;
+    extension: string;
+    isPublic: boolean;
+    fileName?: string;
+    path: {
+      key: string;
+      value: string;
+    }[];
+    metadata: AnyMetadata;
+    replaceTargetUrl?: string;
+    temporary: boolean;
+  };
+  autoSignedUrls?: {
+    expiresIn?: number;
+    includeThumbnails?: boolean;
+  };
+};
+
+export type ProviderFilterValue =
+  | string
+  | Partial<{
+      eq: string;
+      neq: string;
+      gt: string;
+      gte: string;
+      lt: string;
+      lte: string;
+      startsWith: string;
+      endsWith: string;
+      between: [string, string];
+    }>;
+
+export type ListFilesFilter = {
+  AND?: ListFilesFilter[];
+  OR?: ListFilesFilter[];
+  uploadedAt?: ProviderFilterValue;
+  path?: Record<string, ProviderFilterValue>;
+  metadata?: Record<string, ProviderFilterValue>;
+};
+
+export type FileReference = { id: string } | { key: string } | { url: string };
+
+export type ProviderFile = {
+  id: string;
+  url: string;
+  key: string;
+  thumbnailUrl: string | null;
+  thumbnailKey: string | null;
+  bucketId: string;
+  bucketName: string;
+  projectId: string;
+  accountId: string;
+  name: string;
+  path: Record<string, string>;
+  metadata: Record<string, string>;
+  sizeBytes: number;
+  mimeType: string | null;
+  state: 'requested' | 'uploaded' | 'deleted' | 'replace_requested';
+  temporary: boolean;
+  uploadedAt: Date;
+  updatedAt: Date;
+};
+
+export type BackendFile = {
+  url: string;
+  sizeBytes: number;
+  path: Record<string, string>;
+  metadata: Record<string, string>;
+  uploadedAt: Date | string;
+  updatedAt: Date | string;
+};
+
+export type ProviderFileMutationResult<
+  TErrorCode extends string =
+    | 'FILE_NOT_CONFIRMABLE'
+    | 'FILE_NOT_DELETABLE'
+    | 'FILE_NOT_RESTORABLE'
+    | 'INVALID_FILE_REF',
+> = {
+  results: (
+    | { success: true }
+    | {
+        success: false;
+        error: {
+          code: TErrorCode;
+          message: string;
+        };
+      }
+  )[];
+};
+
+export type BackendUploadParams = {
+  bucketName: string;
+  bucketType: string;
+  fileInfo: RequestUploadParams['fileInfo'];
+  autoSignedUrls?: RequestUploadParams['autoSignedUrls'];
+  source: Blob;
+  signal?: AbortSignal;
+  onProgress?: (progress: {
+    transferredBytes: number;
+    totalBytes: number;
+    percentage: number;
+    phase: 'preparing' | 'uploading' | 'processing';
+  }) => void;
+};
+
+export type BackendUploadResult<TFile extends BackendFile = ProviderFile> = {
+  file: TFile;
+  signedReadUrl?: {
+    signedUrl: string;
+    signedThumbnailUrl?: string | null;
+    expiresAt: Date | string;
+    expiresIn: number;
+  };
+};
+
+export type BackendUploadOperation<TFile extends BackendFile = ProviderFile> = (
+  params: BackendUploadParams,
+) => MaybePromise<BackendUploadResult<TFile>>;
+
+export type BackendGetFileOperation<
+  TFile extends BackendFile = ProviderFile,
+  TFileReference = FileReference,
+> = (params: {
+  bucketName: string;
+  file: TFileReference;
+}) => MaybePromise<TFile>;
+
+export type BackendListFilesResult<
+  TFile extends BackendFile = ProviderFile,
+  TCursor = string,
+> = {
+  items: TFile[];
+  limit: number;
+  nextCursor: TCursor | null;
+  hasMore: boolean;
+};
+
+export type BackendListFilesOperation<
+  TFile extends BackendFile = ProviderFile,
+  TCursor = string,
+> = (params: {
+  bucketName: string;
+  filter?: ListFilesFilter;
+  cursor?: TCursor;
+  limit?: number;
+}) => MaybePromise<BackendListFilesResult<TFile, TCursor>>;
+
+export type BackendFileMutationOperation<
+  TFileReference = FileReference,
+  TErrorCode extends string =
+    | 'FILE_NOT_CONFIRMABLE'
+    | 'FILE_NOT_DELETABLE'
+    | 'FILE_NOT_RESTORABLE'
+    | 'INVALID_FILE_REF',
+> = (params: {
+  bucketName: string;
+  files: TFileReference[];
+}) => MaybePromise<ProviderFileMutationResult<TErrorCode>>;
+
+export type BackendGetSignedUrlsOperation<
+  TFileReference = FileReference,
+  TResult extends GetSignedUrlRes = GetSignedUrlRes,
+> = (params: {
+  bucketName: string;
+  files: TFileReference[];
+  expiresIn?: number;
+  includeThumbnails?: boolean;
+}) => MaybePromise<TResult[]>;
+
+export type RequestUploadPartsParams = {
+  multipart: {
+    uploadId: string;
+    parts: number[];
+  };
+  path: string;
+};
+
+export type RequestUploadPartsRes = {
+  multipart: {
+    uploadId: string;
+    parts: {
+      partNumber: number;
+      uploadUrl: string;
+    }[];
+  };
+};
+
+export type CompleteMultipartUploadParams = {
+  uploadId: string;
+  key: string;
+  parts: {
+    partNumber: number;
+    eTag: string;
+  }[];
+};
+
+type RequestUploadAccess = {
+  accessUrl: string;
+  thumbnailUrl?: string | null;
+  accessSignedUrl?: string;
+  accessSignedThumbnailUrl?: string | null;
+  accessSignedUrlExpiresAt?: Date | string;
+  accessSignedUrlExpiresIn?: number;
+};
+
+export type SinglePartRequestUploadRes = RequestUploadAccess & {
+  uploadUrl: string;
+};
+
+export type MultipartRequestUploadRes = RequestUploadAccess & {
+  multipart: {
+    key: string;
+    uploadId: string;
+    partSize: number;
+    totalParts: number;
+    parts: {
+      partNumber: number;
+      uploadUrl: string;
+    }[];
+  };
+};
+
+export type RequestUploadRes =
+  SinglePartRequestUploadRes | MultipartRequestUploadRes;
+
+export type GetSignedUrlRes = {
+  url: string;
+  signedUrl: string;
+  expiresAt: Date;
+  expiresIn: number;
+  thumbnailUrl?: string | null;
+  signedThumbnailUrl?: string | null;
+};
+
+export type ProviderReferenceDefinition<
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
+> = {
+  schema: TSchema;
+  fromUrl: (url: string) => MaybePromise<unknown>;
+};
+
+type ProviderUploadBase<
+  TUpload extends BackendUploadOperation<BackendFile> | undefined =
+    BackendUploadOperation<BackendFile> | undefined,
+> = {
+  upload?: TUpload;
+};
+
+export type ProviderMultipartUploads = {
+  requestParts: (
+    params: RequestUploadPartsParams,
+  ) => MaybePromise<RequestUploadPartsRes>;
+  complete: (params: CompleteMultipartUploadParams) => MaybePromise<void>;
+};
+
+export type ProviderUploads<
+  TUpload extends BackendUploadOperation<BackendFile> | undefined =
+    BackendUploadOperation<BackendFile> | undefined,
+> =
+  | (ProviderUploadBase<TUpload> & {
+      request: (
+        params: RequestUploadParams,
+      ) => MaybePromise<SinglePartRequestUploadRes>;
+      multipart?: never;
+    })
+  | (ProviderUploadBase<TUpload> & {
+      request: (params: RequestUploadParams) => MaybePromise<RequestUploadRes>;
+      multipart: ProviderMultipartUploads;
+    });
+
+export type ProviderFiles<
+  TFileReference = FileReference,
+  TCursor = string,
+  TGet extends BackendGetFileOperation<BackendFile, TFileReference> =
+    BackendGetFileOperation<BackendFile, TFileReference>,
+  TList extends BackendListFilesOperation<BackendFile, TCursor> | undefined =
+    BackendListFilesOperation<BackendFile, TCursor> | undefined,
+  TConfirm extends
+    BackendFileMutationOperation<TFileReference, string> | undefined =
+    BackendFileMutationOperation<TFileReference, string> | undefined,
+  TDelete extends
+    BackendFileMutationOperation<TFileReference, string> | undefined =
+    BackendFileMutationOperation<TFileReference, string> | undefined,
+  TRestore extends
+    BackendFileMutationOperation<TFileReference, string> | undefined =
+    BackendFileMutationOperation<TFileReference, string> | undefined,
+  TGetSignedUrls extends
+    BackendGetSignedUrlsOperation<TFileReference> | undefined =
+    BackendGetSignedUrlsOperation<TFileReference> | undefined,
+> = {
+  cursorSchema?: StandardSchemaV1<unknown, TCursor>;
+  get: TGet;
+  list?: TList;
+  confirm?: TConfirm;
+  delete?: TDelete;
+  restore?: TRestore;
+  getSignedUrls?: TGetSignedUrls;
+};
+
+export type EdgeStoreProvider<
+  TReferenceSchema extends StandardSchemaV1 = StandardSchemaV1<
+    unknown,
+    FileReference
+  >,
+  TCursor = string,
+  TUploads extends ProviderUploads = ProviderUploads,
+  TFiles extends ProviderFiles<
+    StandardSchemaV1.InferOutput<TReferenceSchema>,
+    TCursor
+  > = ProviderFiles<StandardSchemaV1.InferOutput<TReferenceSchema>, TCursor>,
+> = {
+  name: string;
+  baseUrl: string | (() => MaybePromise<string>);
+  init: <TCtx extends AnyContext>(
+    params: InitParams<TCtx>,
+  ) => MaybePromise<InitRes>;
+  reference: ProviderReferenceDefinition<TReferenceSchema>;
+  uploads: TUploads;
+  files: TFiles;
+};
+
+export type AnyEdgeStoreProvider = EdgeStoreProvider<
+  StandardSchemaV1<any, any>,
+  any,
+  ProviderUploads,
+  ProviderFiles<any, any>
+>;
+
+declare const routerFileFieldsProviderBrand: unique symbol;
+
+/**
+ * @internal Marks providers whose read contract persists the router-derived
+ * path and metadata fields.
+ */
+export type RouterFileFieldsProvider = {
+  readonly [routerFileFieldsProviderBrand]: true;
+};
+
+export type DefaultEdgeStoreProvider = EdgeStoreProvider<
+  StandardSchemaV1<unknown, FileReference>,
+  string
+> &
+  RouterFileFieldsProvider & {
+    uploads: ProviderUploads<BackendUploadOperation> & {
+      upload: BackendUploadOperation;
+    };
+    files: ProviderFiles<FileReference, string> & {
+      get: BackendGetFileOperation;
+      list: BackendListFilesOperation;
+      confirm: BackendFileMutationOperation;
+      delete: BackendFileMutationOperation;
+      restore: BackendFileMutationOperation;
+      getSignedUrls: BackendGetSignedUrlsOperation;
+    };
+  };

package/src/internals/sharedFuncTypes.ts

@@ -0,0 +1,38 @@
+import { type Simplify } from '../types';
+import { type AnyMetadata } from './bucketBuilder';
+import {
+  type ClientInit,
+  type RequestUploadPartsRes,
+  type RequestUploadRes,
+} from './providerTypes';
+
+export type SharedInitRes = {
+  newCookies: string[];
+  baseUrl: string;
+  providerName: string;
+  clientInit?: ClientInit;
+};
+export type SharedRequestUploadRes = Simplify<
+  RequestUploadRes & {
+    size: number;
+    uploadedAt: string;
+    path: Record<string, string>;
+    pathOrder: string[];
+    metadata: AnyMetadata;
+  }
+>;
+export type SharedRequestUploadPartsRes = RequestUploadPartsRes;
+
+export type SharedFileMutationRes = {
+  succeeded: string[];
+  failed: {
+    url: string;
+    error: {
+      code: string;
+      message: string;
+    };
+  }[];
+};
+
+export type SharedConfirmUploadsRes = SharedFileMutationRes;
+export type SharedDeleteFilesRes = SharedFileMutationRes;

package/src/internals/types.ts

@@ -0,0 +1,52 @@
+import { type MaybePromise } from '../types';
+
+export type ClientUploadTransform = (params: {
+  file: File;
+  extension: string;
+  signal?: AbortSignal;
+}) => MaybePromise<
+  | File
+  | Blob
+  | {
+      file: File | Blob;
+      extension: string;
+    }
+>;
+
+export type UploadOptions = {
+  /**
+   * e.g. 'my-file-name.jpg'
+   *
+   * By default, a unique file name will be generated for each upload.
+   * If you want to use a custom file name, you can use this option.
+   * If you use the same file name for multiple uploads, the previous file will be overwritten.
+   * But it might take some time for the CDN cache to be cleared.
+   * So maybe you will keep seeing the old file for a while.
+   *
+   * If you want to replace an existing file, immediately leave the `manualFileName` option empty and use the `replaceTargetUrl` option.
+   */
+  manualFileName?: string;
+  /**
+   * Use this to replace an existing file.
+   * It will automatically delete the existing file when the upload is complete.
+   */
+  replaceTargetUrl?: string;
+  /**
+   * If true, the file needs to be confirmed by using the `confirm` function.
+   * If the file is not confirmed within 24 hours, it will be deleted.
+   *
+   * This is useful for pages where the file is uploaded as soon as it is selected,
+   * but the user can leave the page without submitting the form.
+   *
+   * This avoids unnecessary zombie files in the bucket.
+   */
+  temporary?: boolean;
+  /**
+   * Transform the file before it is validated and uploaded.
+   *
+   * This can be used to compress images, convert formats, encrypt files, etc.
+   * The transformed file's size, MIME type, and extension will be used for the
+   * upload request.
+   */
+  transform?: ClientUploadTransform;
+};