Skip to content
rachel/workerd
File

Blob: types/defines/images.d.ts

typescript272 lines
1// Copyright (c) 2024 Cloudflare, Inc.
2// Licensed under the Apache 2.0 license found in the LICENSE file or at:
3//     https://opensource.org/licenses/Apache-2.0
4 
5type ImageInfoResponse =
6  | { format: 'image/svg+xml' }
7  | {
8      format: string;
9      fileSize: number;
10      width: number;
11      height: number;
12    };
13 
14type ImageTransform = {
15  width?: number;
16  height?: number;
17  background?: string;
18  blur?: number;
19  border?:
20    | {
21        color?: string;
22        width?: number;
23      }
24    | {
25        top?: number;
26        bottom?: number;
27        left?: number;
28        right?: number;
29      };
30  brightness?: number;
31  contrast?: number;
32  fit?: 'scale-down' | 'contain' | 'pad' | 'squeeze' | 'cover' | 'crop';
33  flip?: 'h' | 'v' | 'hv';
34  gamma?: number;
35  segment?: 'foreground';
36  gravity?:
37    | 'face'
38    | 'left'
39    | 'right'
40    | 'top'
41    | 'bottom'
42    | 'center'
43    | 'auto'
44    | 'entropy'
45    | {
46        x?: number;
47        y?: number;
48        mode: 'remainder' | 'box-center';
49      };
50  rotate?: 0 | 90 | 180 | 270;
51  saturation?: number;
52  sharpen?: number;
53  trim?:
54    | 'border'
55    | {
56        top?: number;
57        bottom?: number;
58        left?: number;
59        right?: number;
60        width?: number;
61        height?: number;
62        border?:
63          | boolean
64          | {
65              color?: string;
66              tolerance?: number;
67              keep?: number;
68            };
69      };
70};
71 
72type ImageDrawOptions = {
73  opacity?: number;
74  repeat?: boolean | string;
75  top?: number;
76  left?: number;
77  bottom?: number;
78  right?: number;
79};
80 
81type ImageInputOptions = {
82  encoding?: 'base64';
83};
84 
85type ImageOutputOptions = {
86  format:
87    | 'image/jpeg'
88    | 'image/png'
89    | 'image/gif'
90    | 'image/webp'
91    | 'image/avif'
92    | 'rgb'
93    | 'rgba';
94  quality?: number;
95  background?: string;
96  anim?: boolean;
97};
98 
99interface ImageMetadata {
100  id: string;
101  filename?: string;
102  uploaded?: string;
103  requireSignedURLs: boolean;
104  meta?: Record<string, unknown>;
105  variants: string[];
106  draft?: boolean;
107  creator?: string;
108}
109 
110interface ImageUploadOptions {
111  id?: string;
112  filename?: string;
113  requireSignedURLs?: boolean;
114  metadata?: Record<string, unknown>;
115  creator?: string;
116  encoding?: 'base64';
117}
118 
119interface ImageUpdateOptions {
120  requireSignedURLs?: boolean;
121  metadata?: Record<string, unknown>;
122  creator?: string;
123}
124 
125interface ImageListOptions {
126  limit?: number;
127  cursor?: string;
128  sortOrder?: 'asc' | 'desc';
129  creator?: string;
130}
131 
132interface ImageList {
133  images: ImageMetadata[];
134  cursor?: string;
135  listComplete: boolean;
136}
137 
138interface ImageHandle {
139  /**
140   * Get metadata for a hosted image
141   * @returns Image metadata, or null if not found
142   */
143  details(): Promise<ImageMetadata | null>;
144 
145  /**
146   * Get the raw image data for a hosted image
147   * @returns ReadableStream of image bytes, or null if not found
148   */
149  bytes(): Promise<ReadableStream<Uint8Array> | null>;
150 
151  /**
152   * Update hosted image metadata
153   * @param options Properties to update
154   * @returns Updated image metadata
155   * @throws {@link ImagesError} if update fails
156   */
157  update(options: ImageUpdateOptions): Promise<ImageMetadata>;
158 
159  /**
160   * Delete a hosted image
161   * @returns True if deleted, false if not found
162   */
163  delete(): Promise<boolean>;
164}
165 
166interface HostedImagesBinding {
167  /**
168   * Get a handle for a hosted image
169   * @param imageId The ID of the image (UUID or custom ID)
170   * @returns A handle for per-image operations
171   */
172  image(imageId: string): ImageHandle;
173 
174  /**
175   * Upload a new hosted image
176   * @param image The image file to upload
177   * @param options Upload configuration
178   * @returns Metadata for the uploaded image
179   * @throws {@link ImagesError} if upload fails
180   */
181  upload(
182    image: ReadableStream<Uint8Array> | ArrayBuffer,
183    options?: ImageUploadOptions
184  ): Promise<ImageMetadata>;
185 
186  /**
187   * List hosted images with pagination
188   * @param options List configuration
189   * @returns List of images with pagination info
190   * @throws {@link ImagesError} if list fails
191   */
192  list(options?: ImageListOptions): Promise<ImageList>;
193}
194 
195interface ImagesBinding {
196  /**
197   * Get image metadata (type, width and height)
198   * @throws {@link ImagesError} with code 9412 if input is not an image
199   * @param stream The image bytes
200   */
201  info(
202    stream: ReadableStream<Uint8Array>,
203    options?: ImageInputOptions
204  ): Promise<ImageInfoResponse>;
205  /**
206   * Begin applying a series of transformations to an image
207   * @param stream The image bytes
208   * @returns A transform handle
209   */
210  input(
211    stream: ReadableStream<Uint8Array>,
212    options?: ImageInputOptions
213  ): ImageTransformer;
214 
215  /**
216   * Access hosted images CRUD operations
217   */
218  readonly hosted: HostedImagesBinding;
219}
220 
221interface ImageTransformer {
222  /**
223   * Apply transform next, returning a transform handle.
224   * You can then apply more transformations, draw, or retrieve the output.
225   * @param transform
226   */
227  transform(transform: ImageTransform): ImageTransformer;
228 
229  /**
230   * Draw an image on this transformer, returning a transform handle.
231   * You can then apply more transformations, draw, or retrieve the output.
232   * @param image The image (or transformer that will give the image) to draw
233   * @param options The options configuring how to draw the image
234   */
235  draw(
236    image: ReadableStream<Uint8Array> | ImageTransformer,
237    options?: ImageDrawOptions
238  ): ImageTransformer;
239 
240  /**
241   * Retrieve the image that results from applying the transforms to the
242   * provided input
243   * @param options Options that apply to the output e.g. output format
244   */
245  output(options: ImageOutputOptions): Promise<ImageTransformationResult>;
246}
247 
248type ImageTransformationOutputOptions = {
249  encoding?: 'base64';
250};
251 
252interface ImageTransformationResult {
253  /**
254   * The image as a response, ready to store in cache or return to users
255   */
256  response(): Response;
257  /**
258   * The content type of the returned image
259   */
260  contentType(): string;
261  /**
262   * The bytes of the response
263   */
264  image(options?: ImageTransformationOutputOptions): ReadableStream<Uint8Array>;
265}
266 
267interface ImagesError extends Error {
268  readonly code: number;
269  readonly message: string;
270  readonly stack?: string;
271}