Skip to content
rachel/workerd
File

Blob: src/cloudflare/internal/images.d.ts

typescript275 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  /**
117   * If 'base64', the input data will be decoded from base64 before processing
118   */
119  encoding?: 'base64';
120}
121 
122interface ImageUpdateOptions {
123  requireSignedURLs?: boolean;
124  metadata?: Record<string, unknown>;
125  creator?: string;
126}
127 
128interface ImageListOptions {
129  limit?: number;
130  cursor?: string;
131  sortOrder?: 'asc' | 'desc';
132  creator?: string;
133}
134 
135interface ImageList {
136  images: ImageMetadata[];
137  cursor?: string;
138  listComplete: boolean;
139}
140 
141interface ImageHandle {
142  /**
143   * Get metadata for a hosted image
144   * @returns Image metadata, or null if not found
145   */
146  details(): Promise<ImageMetadata | null>;
147 
148  /**
149   * Get the raw image data for a hosted image
150   * @returns ReadableStream of image bytes, or null if not found
151   */
152  bytes(): Promise<ReadableStream<Uint8Array> | null>;
153 
154  /**
155   * Update hosted image metadata
156   * @param options Properties to update
157   * @returns Updated image metadata
158   * @throws {@link ImagesError} if update fails
159   */
160  update(options: ImageUpdateOptions): Promise<ImageMetadata>;
161 
162  /**
163   * Delete a hosted image
164   * @returns True if deleted, false if not found
165   */
166  delete(): Promise<boolean>;
167}
168 
169interface HostedImagesBinding {
170  /**
171   * Get a handle for a hosted image
172   * @param imageId The ID of the image (UUID or custom ID)
173   * @returns A handle for per-image operations
174   */
175  image(imageId: string): ImageHandle;
176 
177  /**
178   * Upload a new hosted image
179   * @param image The image file to upload
180   * @param options Upload configuration
181   * @returns Metadata for the uploaded image
182   * @throws {@link ImagesError} if upload fails
183   */
184  upload(
185    image: ReadableStream<Uint8Array> | ArrayBuffer,
186    options?: ImageUploadOptions
187  ): Promise<ImageMetadata>;
188 
189  /**
190   * List hosted images with pagination
191   * @param options List configuration
192   * @returns List of images with pagination info
193   * @throws {@link ImagesError} if list fails
194   */
195  list(options?: ImageListOptions): Promise<ImageList>;
196}
197 
198interface ImagesBinding {
199  /**
200   * Get image metadata (type, width and height)
201   * @throws {@link ImagesError} with code 9412 if input is not an image
202   * @param stream The image bytes
203   */
204  info(
205    stream: ReadableStream<Uint8Array>,
206    options?: ImageInputOptions
207  ): Promise<ImageInfoResponse>;
208  /**
209   * Begin applying a series of transformations to an image
210   * @param stream The image bytes
211   * @returns A transform handle
212   */
213  input(
214    stream: ReadableStream<Uint8Array>,
215    options?: ImageInputOptions
216  ): ImageTransformer;
217 
218  /**
219   * Access hosted images CRUD operations
220   */
221  readonly hosted: HostedImagesBinding;
222}
223 
224interface ImageTransformer {
225  /**
226   * Apply transform next, returning a transform handle.
227   * You can then apply more transformations, draw, or retrieve the output.
228   * @param transform
229   */
230  transform(transform: ImageTransform): ImageTransformer;
231 
232  /**
233   * Draw an image on this transformer, returning a transform handle.
234   * You can then apply more transformations, draw, or retrieve the output.
235   * @param image The image (or transformer that will give the image) to draw
236   * @param options The options configuring how to draw the image
237   */
238  draw(
239    image: ReadableStream<Uint8Array> | ImageTransformer,
240    options?: ImageDrawOptions
241  ): ImageTransformer;
242 
243  /**
244   * Retrieve the image that results from applying the transforms to the
245   * provided input
246   * @param options Options that apply to the output e.g. output format
247   */
248  output(options: ImageOutputOptions): Promise<ImageTransformationResult>;
249}
250 
251type ImageTransformationOutputOptions = {
252  encoding?: 'base64';
253};
254 
255interface ImageTransformationResult {
256  /**
257   * The image as a response, ready to store in cache or return to users
258   */
259  response(): Response;
260  /**
261   * The content type of the returned image
262   */
263  contentType(): string;
264  /**
265   * The bytes of the response
266   */
267  image(options?: ImageTransformationOutputOptions): ReadableStream<Uint8Array>;
268}
269 
270interface ImagesError extends Error {
271  readonly code: number;
272  readonly message: string;
273  readonly stack?: string;
274}