react-smart-copy 1.12.0 → 1.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +87 -3
- package/dist/code.cjs +58 -6
- package/dist/code.cjs.map +1 -1
- package/dist/code.js +58 -6
- package/dist/code.js.map +1 -1
- package/dist/image.cjs +1293 -0
- package/dist/image.cjs.map +1 -0
- package/dist/image.d.cts +217 -0
- package/dist/image.d.ts +217 -0
- package/dist/image.js +1282 -0
- package/dist/image.js.map +1 -0
- package/package.json +50 -18
package/dist/image.d.ts
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
//#region src/image/bytes.d.ts
|
|
2
|
+
export declare const DEFAULT_IMAGE_MAX_INPUT_BYTES: number;
|
|
3
|
+
//#endregion
|
|
4
|
+
//#region src/image/types.d.ts
|
|
5
|
+
/** Formats recognised from their bytes (never from a file name or a claimed MIME type). */
|
|
6
|
+
type ImageFormat = 'jpeg' | 'png' | 'gif' | 'webp' | 'avif' | 'heic' | 'bmp';
|
|
7
|
+
/**
|
|
8
|
+
* Kinds of metadata an image can carry.
|
|
9
|
+
*
|
|
10
|
+
* - `exif`: camera, settings, dates, serial numbers (Exif / TIFF tags).
|
|
11
|
+
* - `gps`: a location, inside Exif.
|
|
12
|
+
* - `thumbnail`: an embedded preview, which can show the uncropped original.
|
|
13
|
+
* - `xmp`: Adobe XMP (edit history, authors, often a copy of Exif).
|
|
14
|
+
* - `iptc`: captions, credits and keywords (Photoshop IRB / IPTC).
|
|
15
|
+
* - `comment`: free-text comments (JPEG COM, GIF comment extension).
|
|
16
|
+
* - `text`: text chunks (PNG `tEXt`, `zTXt`, `iTXt`, `tIME`).
|
|
17
|
+
* - `icc`: an ICC colour profile. Kept by default: it changes how colours look.
|
|
18
|
+
* - `other`: anything else outside the image data: vendor segments, multi-picture
|
|
19
|
+
* (MPF) and depth images, content credentials (C2PA), data appended after the
|
|
20
|
+
* image (motion photos), unknown chunks.
|
|
21
|
+
*/
|
|
22
|
+
type MetadataKind = 'exif' | 'gps' | 'thumbnail' | 'xmp' | 'iptc' | 'comment' | 'text' | 'icc' | 'other';
|
|
23
|
+
/** Every metadata kind, in a stable order. */
|
|
24
|
+
export declare const METADATA_KINDS: readonly MetadataKind[];
|
|
25
|
+
interface ImageInfo {
|
|
26
|
+
/** `null` when the bytes are not a format this module reads. */
|
|
27
|
+
readonly format: ImageFormat | null;
|
|
28
|
+
/** e.g. `image/jpeg`; `null` when `format` is. */
|
|
29
|
+
readonly mimeType: string | null;
|
|
30
|
+
/** Stored pixel size (before orientation), when the header gives it. */
|
|
31
|
+
readonly width: number | null;
|
|
32
|
+
readonly height: number | null;
|
|
33
|
+
/** Exif orientation, 1-8 (1 = as stored). Browsers apply it when they draw the image. */
|
|
34
|
+
readonly orientation: number;
|
|
35
|
+
/** Several frames: an animated GIF, PNG (APNG), WebP or AVIF. */
|
|
36
|
+
readonly animated: boolean;
|
|
37
|
+
/** What the file carries besides the image itself, in the order of {@link METADATA_KINDS}. */
|
|
38
|
+
readonly metadata: readonly MetadataKind[];
|
|
39
|
+
}
|
|
40
|
+
//#endregion
|
|
41
|
+
//#region src/image/info.d.ts
|
|
42
|
+
interface ReadImageInfoOptions {
|
|
43
|
+
/** Refuse files larger than this. Default {@link DEFAULT_IMAGE_MAX_INPUT_BYTES} (100 MiB). */
|
|
44
|
+
readonly maxInputBytes?: number;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* What an image file is and what it carries, read from its bytes without
|
|
48
|
+
* decoding the picture: format, stored size, orientation, animation, and the
|
|
49
|
+
* metadata in it (Exif, GPS location, thumbnails, XMP, IPTC, comments, colour
|
|
50
|
+
* profile, appended data). The claimed MIME type and file name are never
|
|
51
|
+
* trusted. Works anywhere, including on the server.
|
|
52
|
+
*
|
|
53
|
+
* @example
|
|
54
|
+
* const info = await readImageInfo(file);
|
|
55
|
+
* if (info.metadata.includes('gps')) warn('This photo contains its location.');
|
|
56
|
+
*/
|
|
57
|
+
export declare function readImageInfo(blob: Blob, options?: ReadImageInfoOptions): Promise<ImageInfo>;
|
|
58
|
+
interface StripMetadataOptions extends ReadImageInfoOptions {
|
|
59
|
+
/** Keep the ICC colour profile, which changes how colours display. Default `true`. */
|
|
60
|
+
readonly keepColorProfile?: boolean;
|
|
61
|
+
/**
|
|
62
|
+
* Keep the Exif orientation (as a 26-byte Exif block with nothing else), so a
|
|
63
|
+
* photo still displays the right way up. Default `true`.
|
|
64
|
+
*/
|
|
65
|
+
readonly keepOrientation?: boolean;
|
|
66
|
+
}
|
|
67
|
+
interface StrippedImage {
|
|
68
|
+
/** The image without its metadata: the same Blob when there was nothing to remove, a File when given one. */
|
|
69
|
+
readonly blob: Blob;
|
|
70
|
+
/** What the input held. */
|
|
71
|
+
readonly info: ImageInfo;
|
|
72
|
+
/** What was removed, in the order of {@link METADATA_KINDS}. */
|
|
73
|
+
readonly removed: readonly MetadataKind[];
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Removes metadata from a JPEG, PNG, WebP or GIF without re-encoding it: the
|
|
77
|
+
* picture stays bit-for-bit the same. Removes Exif (camera, dates, serial
|
|
78
|
+
* numbers, GPS location), embedded thumbnails, XMP, IPTC, comments, text chunks,
|
|
79
|
+
* multi-picture and depth images, content credentials and data appended after
|
|
80
|
+
* the image. Keeps the colour profile and orientation unless told otherwise.
|
|
81
|
+
* Works anywhere, including on the server.
|
|
82
|
+
*
|
|
83
|
+
* AVIF and HEIC can't be stripped losslessly: this throws `unsupported-format`
|
|
84
|
+
* for them (and for files that aren't images); `prepareImage` re-encodes them.
|
|
85
|
+
*
|
|
86
|
+
* @example
|
|
87
|
+
* const { blob, removed } = await stripMetadata(file);
|
|
88
|
+
* if (removed.includes('gps')) notice('Location removed from the photo.');
|
|
89
|
+
*/
|
|
90
|
+
export declare function stripMetadata(blob: Blob, options?: StripMetadataOptions): Promise<StrippedImage>;
|
|
91
|
+
//#endregion
|
|
92
|
+
//#region src/image/prepare.d.ts
|
|
93
|
+
/** Formats `prepareImage` can write. */
|
|
94
|
+
type OutputImageType = 'image/png' | 'image/jpeg' | 'image/webp';
|
|
95
|
+
/** A decoded picture, already turned the right way up. */
|
|
96
|
+
interface DecodedImage {
|
|
97
|
+
readonly width: number;
|
|
98
|
+
readonly height: number;
|
|
99
|
+
/** Platform-specific (an `ImageBitmap` in browsers). */
|
|
100
|
+
readonly source: unknown;
|
|
101
|
+
/** Frees the decoded pixels. */
|
|
102
|
+
readonly close: () => void;
|
|
103
|
+
}
|
|
104
|
+
interface EncodeTarget {
|
|
105
|
+
readonly width: number;
|
|
106
|
+
readonly height: number;
|
|
107
|
+
readonly type: OutputImageType;
|
|
108
|
+
/** 0-1, for JPEG and WebP. */
|
|
109
|
+
readonly quality: number;
|
|
110
|
+
/** CSS colour painted under transparent pixels; always set for JPEG, which has no transparency. */
|
|
111
|
+
readonly background: string | null;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Everything `prepareImage` needs from the platform. The default uses
|
|
115
|
+
* `createImageBitmap` and a canvas (`OffscreenCanvas` when there is one, so it
|
|
116
|
+
* also works in workers). Inject your own for other decoders (e.g. a WebAssembly
|
|
117
|
+
* HEIC decoder), native shells or tests.
|
|
118
|
+
*/
|
|
119
|
+
interface ImageEnvironment {
|
|
120
|
+
readonly decode: (blob: Blob, signal: AbortSignal) => Promise<DecodedImage>;
|
|
121
|
+
/** Draws the image at the target size and encodes it. May return another type when the browser can't encode the one asked for. */
|
|
122
|
+
readonly encode: (image: DecodedImage, target: EncodeTarget, signal: AbortSignal) => Promise<Blob>;
|
|
123
|
+
}
|
|
124
|
+
/** The browser environment, or `null` where there is no `createImageBitmap` or canvas (servers, old browsers). */
|
|
125
|
+
export declare function getDefaultImageEnvironment(): ImageEnvironment | null;
|
|
126
|
+
export declare const DEFAULT_IMAGE_MAX_INPUT_PIXELS = 100000000;
|
|
127
|
+
/** 4096 x 4096: the canvas area limit of Safari and iOS, the strictest mainstream engine. */
|
|
128
|
+
export declare const DEFAULT_IMAGE_MAX_PIXELS = 16777216;
|
|
129
|
+
export declare const DEFAULT_IMAGE_QUALITY = 0.85;
|
|
130
|
+
export declare const DEFAULT_IMAGE_MIN_QUALITY = 0.5;
|
|
131
|
+
export declare const DEFAULT_IMAGE_TIMEOUT_MS = 30000;
|
|
132
|
+
interface PrepareImageOptions {
|
|
133
|
+
/** Largest width and height of the result, in pixels. Default: no limit. Images are only made smaller, never larger. */
|
|
134
|
+
readonly maxWidth?: number;
|
|
135
|
+
readonly maxHeight?: number;
|
|
136
|
+
/** Largest pixel area of the result. Default {@link DEFAULT_IMAGE_MAX_PIXELS} (fits Safari's canvas limit). */
|
|
137
|
+
readonly maxPixels?: number;
|
|
138
|
+
/**
|
|
139
|
+
* Largest file size of the result, in bytes. Default: no limit. Lossy formats
|
|
140
|
+
* lower their quality down to `minQuality` first, then the size is reduced.
|
|
141
|
+
* When it can't be met, a `too-large` error says so; the file is never left too big.
|
|
142
|
+
*/
|
|
143
|
+
readonly maxBytes?: number;
|
|
144
|
+
/**
|
|
145
|
+
* The format to write. `'auto'` (the default) keeps PNG, JPEG and WebP as they
|
|
146
|
+
* are; GIF and BMP become PNG, AVIF and HEIC become JPEG; and a PNG that can't
|
|
147
|
+
* fit `maxBytes` becomes WebP (or JPEG where WebP can't be encoded).
|
|
148
|
+
*/
|
|
149
|
+
readonly type?: 'auto' | OutputImageType;
|
|
150
|
+
/** Quality to start from for JPEG and WebP, 0-1. Default 0.85. */
|
|
151
|
+
readonly quality?: number;
|
|
152
|
+
/** Lowest quality to go to before reducing the size. Default 0.5. */
|
|
153
|
+
readonly minQuality?: number;
|
|
154
|
+
/** CSS colour under transparent pixels when writing JPEG. Default `'#fff'`. */
|
|
155
|
+
readonly background?: string;
|
|
156
|
+
/**
|
|
157
|
+
* Animated GIF, PNG and WebP: `'keep'` (the default) keeps every frame and only
|
|
158
|
+
* removes metadata, so a resize or `maxBytes` it can't meet is a `too-large` error;
|
|
159
|
+
* `'first-frame'` turns it into a still image; `'reject'` refuses it with `unsupported-format`.
|
|
160
|
+
*/
|
|
161
|
+
readonly animated?: 'keep' | 'first-frame' | 'reject';
|
|
162
|
+
/** Keep the colour profile when no re-encoding is needed. Re-encoded images are written in sRGB. Default `true`. */
|
|
163
|
+
readonly keepColorProfile?: boolean;
|
|
164
|
+
/** Refuse inputs with more pixels than this, before decoding them (decompression bombs). Default 100 000 000. */
|
|
165
|
+
readonly maxInputPixels?: number;
|
|
166
|
+
/** Refuse files larger than this. Default 100 MiB. */
|
|
167
|
+
readonly maxInputBytes?: number;
|
|
168
|
+
/** Give up after this long. Default 30 000 ms. `Infinity` disables. */
|
|
169
|
+
readonly timeoutMs?: number;
|
|
170
|
+
readonly signal?: AbortSignal;
|
|
171
|
+
/** Platform hooks. Defaults to the browser. */
|
|
172
|
+
readonly environment?: ImageEnvironment;
|
|
173
|
+
}
|
|
174
|
+
interface PreparedImage {
|
|
175
|
+
/** The result: a File (named like the input, with the new extension) when given a File, else a Blob. */
|
|
176
|
+
readonly file: Blob;
|
|
177
|
+
readonly type: string;
|
|
178
|
+
/** Pixel size as displayed (orientation applied). `null` when the image was only stripped and its size is unknown. */
|
|
179
|
+
readonly width: number | null;
|
|
180
|
+
readonly height: number | null;
|
|
181
|
+
/** Bytes. */
|
|
182
|
+
readonly size: number;
|
|
183
|
+
/** Whether the picture was decoded and written again (`false`: only metadata was removed, losslessly). */
|
|
184
|
+
readonly reencoded: boolean;
|
|
185
|
+
/** Whether it was made smaller. */
|
|
186
|
+
readonly resized: boolean;
|
|
187
|
+
/** The JPEG or WebP quality used, else `null`. */
|
|
188
|
+
readonly quality: number | null;
|
|
189
|
+
/** Metadata the input had and the result doesn't, in the order of {@link METADATA_KINDS}. */
|
|
190
|
+
readonly removed: readonly MetadataKind[];
|
|
191
|
+
/** The input. */
|
|
192
|
+
readonly original: {
|
|
193
|
+
readonly info: ImageInfo;
|
|
194
|
+
readonly size: number;
|
|
195
|
+
};
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Prepares an image for upload: removes metadata (location, camera, thumbnails),
|
|
199
|
+
* makes it fit `maxWidth` / `maxHeight` / `maxPixels`, and compresses it under
|
|
200
|
+
* `maxBytes`. When nothing has to change but the metadata, the picture is not
|
|
201
|
+
* re-encoded at all, so screenshots and photos keep every pixel. Inputs are
|
|
202
|
+
* checked against `maxInputPixels` from their header, before decoding.
|
|
203
|
+
*
|
|
204
|
+
* Needs a browser (`createImageBitmap` and a canvas) only when it has to
|
|
205
|
+
* re-encode; elsewhere that is an `unsupported` error. Every failure is a typed
|
|
206
|
+
* `CopyFailure`: `too-large`, `unsupported-format`, `timeout`, `aborted`, ...
|
|
207
|
+
*
|
|
208
|
+
* @example
|
|
209
|
+
* usePaste({ accept: ['image'], onPaste: async ({ imageFiles }) => {
|
|
210
|
+
* const image = await prepareImage(imageFiles[0], { maxWidth: 2048, maxBytes: 1_000_000 });
|
|
211
|
+
* upload(image.file);
|
|
212
|
+
* } });
|
|
213
|
+
*/
|
|
214
|
+
export declare function prepareImage(source: Blob, options?: PrepareImageOptions): Promise<PreparedImage>;
|
|
215
|
+
//#endregion
|
|
216
|
+
export type { DecodedImage, EncodeTarget, ImageEnvironment, ImageFormat, ImageInfo, MetadataKind, OutputImageType, PrepareImageOptions, PreparedImage, ReadImageInfoOptions, StripMetadataOptions, StrippedImage };
|
|
217
|
+
//# sourceMappingURL=image.d.ts.map
|