react-smart-copy 1.19.1 → 1.21.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.
@@ -0,0 +1,311 @@
1
+
2
+ //#region src/files/types.d.ts
3
+ /** What a file is for, by its content. */
4
+ type FileFamily = 'image' | 'audio' | 'video' | 'document' | 'archive' | 'text' | 'font' | 'executable' | 'data';
5
+ /** A file type recognised from the file's bytes, never from its name or its claimed MIME type. */
6
+ interface DetectedType {
7
+ /** The MIME type to store and serve it as, e.g. `application/pdf`. */
8
+ readonly mime: string;
9
+ readonly family: FileFamily;
10
+ /** Extensions this type is saved with, lowercase and without the dot; the first is the usual one. */
11
+ readonly extensions: readonly string[];
12
+ /**
13
+ * The container it is a kind of: `application/zip` for a Word document, `text/plain` for
14
+ * JSON. A file named for the container is not a mismatch (`.zip` holding a `.docx`).
15
+ */
16
+ readonly parent: string | null;
17
+ }
18
+ /**
19
+ * Why a file may be unsafe to accept. Each is reported by {@link inspectFile}; the ones in
20
+ * `block` (all of them by default) make {@link acceptFiles} reject the file.
21
+ *
22
+ * - `executable`: a program or script, by content (`MZ`, ELF, Mach-O, `#!`, a shortcut) or
23
+ * by a name the operating system runs (`.exe`, `.bat`, `.ps1`, `.js`, `.jar`, `.iso`, ...).
24
+ * - `active-content`: runs script when opened in a browser from your origin: HTML, SVG, XHTML.
25
+ * - `macros`: an Office file that can hold macros (`.docm`, `.xlsm`, or a `vbaProject.bin`).
26
+ * - `type-mismatch`: the content is not what the extension says (`report.pdf` holding HTML).
27
+ * - `double-extension`: a document or image extension hiding an executable one (`invoice.pdf.exe`).
28
+ * - `hidden-characters`: the name holds bidirectional controls, invisible or control characters,
29
+ * which can make `invoice\u202Egpj.exe` display as `invoiceexe.jpg`.
30
+ * - `empty`: the file has no bytes (a folder dragged where folders are not read, or a failed save).
31
+ */
32
+ type FileRisk = 'executable' | 'active-content' | 'macros' | 'type-mismatch' | 'double-extension' | 'hidden-characters' | 'empty';
33
+ /** Every risk, in a stable order. */
34
+ export declare const FILE_RISKS: readonly FileRisk[];
35
+ interface FileInspection {
36
+ /** The name as given, which may be unsafe to display or store. */
37
+ readonly name: string;
38
+ /** The name made safe to show and store: see {@link safeFileName}. */
39
+ readonly safeName: string;
40
+ /** The last extension, lowercase and without the dot; `null` when there is none. */
41
+ readonly extension: string | null;
42
+ readonly size: number;
43
+ /** The MIME type the browser or caller claimed. Never trusted: kept for reference. */
44
+ readonly declaredType: string;
45
+ /** What the bytes are, or `null` when they are not a type this module recognises. */
46
+ readonly detected: DetectedType | null;
47
+ /**
48
+ * The type to store and serve the file as: the detected one, or `application/octet-stream`
49
+ * when the content is not recognised (never the claimed type).
50
+ */
51
+ readonly type: string;
52
+ /** Whether the content contradicts the extension. Also listed in `risks`. */
53
+ readonly mismatch: boolean;
54
+ /** In the order of {@link FILE_RISKS}. */
55
+ readonly risks: readonly FileRisk[];
56
+ }
57
+ //#endregion
58
+ //#region src/files/accept.d.ts
59
+ /** The tokens of an `accept` list, as in `<input type="file" accept>`: `.pdf`, `image/*`, `text/csv`. Lowercase. */
60
+ export declare function parseAccept(accept: string | readonly string[]): readonly string[];
61
+ /**
62
+ * Whether a file fits an `accept` list, judged by its content. An extension token (`.pdf`)
63
+ * matches the name, when the content does not contradict it. A MIME token (`application/pdf`,
64
+ * `image/*`) matches the detected type or its container; plain text also matches the type its
65
+ * extension names (`text/csv` for `data.csv`). The claimed type is never used. An empty list
66
+ * accepts everything.
67
+ */
68
+ export declare function matchesAccept(inspection: FileInspection, accept: string | readonly string[]): boolean;
69
+ //#endregion
70
+ //#region src/files/name.d.ts
71
+ /** File names: making them safe to show and store, and what they say about the file. */
72
+ /**
73
+ * Extensions the operating system runs, or mounts, when the file is opened: Windows, macOS
74
+ * and Linux programs, scripts and installers, shortcuts, and disk images (which can carry
75
+ * programs past download warnings).
76
+ */
77
+ export declare const EXECUTABLE_EXTENSIONS: ReadonlySet<string>;
78
+ /** The last extension of `name`, lowercase, without the dot; `null` for none (`README`, `.env`). */
79
+ export declare function extensionOf(name: string): string | null;
80
+ interface SafeFileNameOptions {
81
+ /** Longest name, in UTF-8 bytes (what file systems limit). Default 255. The extension is kept. */
82
+ readonly maxBytes?: number;
83
+ /** Put in place of characters that can't be in a file name. Default `_`. */
84
+ readonly replacement?: string;
85
+ /** The name to use when nothing usable is left. Default `file`. */
86
+ readonly fallback?: string;
87
+ }
88
+ /**
89
+ * `name` made safe to show and to store on any operating system:
90
+ *
91
+ * - only the last path segment is kept, so `../../etc/passwd` becomes `passwd`;
92
+ * - bidirectional controls, invisible and control characters are removed (tabs and line breaks become spaces);
93
+ * - characters Windows, macOS or Linux reject (`<>:"/\|?*`) become `replacement`;
94
+ * - runs of whitespace become one space, and leading dots and spaces and trailing dots and
95
+ * spaces are removed (no hidden files, nothing Windows would change);
96
+ * - Windows device names (`CON`, `NUL`, `COM1`, ...) are prefixed with `replacement`;
97
+ * - the result is at most `maxBytes` long in UTF-8, keeping the extension; Unicode is NFC.
98
+ *
99
+ * Never empty: `fallback` is used when nothing is left. Idempotent.
100
+ */
101
+ export declare function safeFileName(name: string, options?: SafeFileNameOptions): string;
102
+ //#endregion
103
+ //#region src/files/collect.d.ts
104
+ export declare const DEFAULT_MAX_FILES = 100;
105
+ export declare const DEFAULT_MAX_FILE_BYTES: number;
106
+ export declare const DEFAULT_MAX_TOTAL_BYTES: number;
107
+ export declare const DEFAULT_MAX_FOLDER_DEPTH = 8;
108
+ /**
109
+ * Where files come from: a paste or drop event (DOM or React), its `DataTransfer`, a
110
+ * `FileList` (`<input type="file">`), or any list of Files and Blobs.
111
+ */
112
+ type FileSource = DataTransfer | {
113
+ readonly clipboardData: DataTransfer | null;
114
+ } | {
115
+ readonly dataTransfer: DataTransfer | null;
116
+ } | Iterable<Blob> | ArrayLike<Blob>;
117
+ /** Why {@link acceptFiles} turned a file (or a folder) away. */
118
+ type FileRejectReason =
119
+ /** It has a risk listed in `block`; `risks` says which. */
120
+ 'blocked' |
121
+ /** It does not fit `accept`. */
122
+ 'not-accepted' |
123
+ /** Larger than `maxFileBytes`. */
124
+ 'too-large' |
125
+ /** Accepting it would take the accepted files over `maxTotalBytes`. */
126
+ 'total-too-large' |
127
+ /** More than `maxFiles` files: this one and any after it were left out (`truncated`). */
128
+ 'too-many' |
129
+ /** A folder deeper than `maxDepth`: its contents were not read. `file` is `null`. */
130
+ 'too-deep' |
131
+ /** It (or, with `file: null`, a folder) could not be read: deleted, moved or blocked by the system. */
132
+ 'unreadable' |
133
+ /** The same bytes as a file accepted before it (only checked with `digest: true`). */
134
+ 'duplicate';
135
+ interface AcceptedFile {
136
+ /** The file as it came. Its `name` and `type` are not safe to use: see `upload`. */
137
+ readonly file: Blob;
138
+ /**
139
+ * The file to upload or store: the same bytes, named `name`, typed as `type` (a `File`, where
140
+ * the platform has one). Its type is the detected one, never the claimed one.
141
+ */
142
+ readonly upload: Blob;
143
+ /** The safe name. */
144
+ readonly name: string;
145
+ /** Where it was in the dropped folders, as safe names joined with `/` (`photos/2024/a.jpg`); just `name` for a loose file. */
146
+ readonly path: string;
147
+ readonly size: number;
148
+ /** The detected type, or `application/octet-stream`. */
149
+ readonly type: string;
150
+ readonly inspection: FileInspection;
151
+ /** Lowercase hex SHA-256 of the content, with `digest: true`; otherwise `null`. */
152
+ readonly sha256: string | null;
153
+ }
154
+ interface RejectedFile {
155
+ /** The file; `null` for a folder (`too-deep`, `unreadable`) or a dropped file the system would not give (`unreadable`). */
156
+ readonly file: Blob | null;
157
+ /** Safe name of the file or folder. */
158
+ readonly name: string;
159
+ /** Safe path, as in {@link AcceptedFile.path}. */
160
+ readonly path: string;
161
+ readonly reason: FileRejectReason;
162
+ /** The file's risks, when it was inspected (all of them, not only the blocked ones). */
163
+ readonly risks: readonly FileRisk[];
164
+ /** A sentence for people, naming the file by its safe name. */
165
+ readonly message: string;
166
+ }
167
+ interface AcceptFilesResult {
168
+ /** In the order they were found: the order of the drop, folders depth-first. */
169
+ readonly accepted: readonly AcceptedFile[];
170
+ readonly rejected: readonly RejectedFile[];
171
+ /** Total size of `accepted`, in bytes. */
172
+ readonly totalBytes: number;
173
+ /** More files were dropped than `maxFiles`: folders were not read to the end. */
174
+ readonly truncated: boolean;
175
+ }
176
+ interface AcceptFilesOptions {
177
+ /** Types to accept, as in `<input accept>`: `".pdf,image/*"` or `['.csv', 'text/plain']`. Judged by content. Default: any. */
178
+ readonly accept?: string | readonly string[];
179
+ /** Risks that reject a file. Default: every one of {@link FILE_RISKS}. `[]` accepts risky files (their `inspection.risks` still say). */
180
+ readonly block?: readonly FileRisk[];
181
+ /** Most files to accept. Default 100. */
182
+ readonly maxFiles?: number;
183
+ /** Largest single file, in bytes. Default 100 MiB. */
184
+ readonly maxFileBytes?: number;
185
+ /** Largest total of the accepted files, in bytes. Default 1 GiB. */
186
+ readonly maxTotalBytes?: number;
187
+ /** Read dropped folders (and the folders in them). Default `true`. With `false`, a folder is an `empty` file. */
188
+ readonly folders?: boolean;
189
+ /** Deepest folder level read: 1 reads only the dropped folder's own files. Default 8. */
190
+ readonly maxDepth?: number;
191
+ /** Compute each file's SHA-256 (reading it whole) and reject repeated content as `duplicate`. Default `false`. */
192
+ readonly digest?: boolean;
193
+ /** How names are made safe. */
194
+ readonly names?: SafeFileNameOptions;
195
+ /** Stops reading; the promise then rejects with an `aborted` CopyFailure. */
196
+ readonly signal?: AbortSignal;
197
+ }
198
+ /** `1048576` as `1 MB`. */
199
+ export declare function formatBytes(bytes: number): string;
200
+ /**
201
+ * Takes the files from a paste, a drop (folders included), a file input or a list, and
202
+ * decides for each whether it is safe and wanted: its type is read from its content, its
203
+ * name made safe, and the limits applied. Nothing is uploaded or read whole (except with
204
+ * `digest`): only each file's first 8 KiB.
205
+ *
206
+ * Call it from the event handler, before anything is awaited: a `DataTransfer` is emptied
207
+ * when its event ends. Folders are read through `webkitGetAsEntry` (every current browser).
208
+ *
209
+ * ```ts
210
+ * onDrop={(event) => {
211
+ * event.preventDefault();
212
+ * void acceptFiles(event, { accept: '.pdf,image/*', maxFileBytes: 20e6 }).then(({ accepted, rejected }) => { ... });
213
+ * }}
214
+ * ```
215
+ *
216
+ * @throws {CopyFailure} `aborted` when `signal` aborts; `unsupported` for `digest` without Web Crypto;
217
+ * `invalid-payload` for a negative limit.
218
+ */
219
+ export declare function acceptFiles(source: FileSource, options?: AcceptFilesOptions): Promise<AcceptFilesResult>;
220
+ //#endregion
221
+ //#region src/files/detect.d.ts
222
+ /** How many leading bytes {@link detectFileType} reads: enough for every signature and a text sniff. */
223
+ export declare const FILE_SNIFF_BYTES = 8192;
224
+ /** Every type this module recognises, by MIME type. */
225
+ export declare const FILE_TYPES: {
226
+ readonly pdf: DetectedType;
227
+ readonly png: DetectedType;
228
+ readonly jpeg: DetectedType;
229
+ readonly gif: DetectedType;
230
+ readonly webp: DetectedType;
231
+ readonly avif: DetectedType;
232
+ readonly heic: DetectedType;
233
+ readonly bmp: DetectedType;
234
+ readonly ico: DetectedType;
235
+ readonly tiff: DetectedType;
236
+ readonly psd: DetectedType;
237
+ readonly svg: DetectedType;
238
+ readonly mp3: DetectedType;
239
+ readonly wav: DetectedType;
240
+ readonly flac: DetectedType;
241
+ readonly ogg: DetectedType;
242
+ readonly m4a: DetectedType;
243
+ readonly mp4: DetectedType;
244
+ readonly mov: DetectedType;
245
+ readonly threegp: DetectedType;
246
+ readonly webm: DetectedType;
247
+ readonly mkv: DetectedType;
248
+ readonly avi: DetectedType;
249
+ readonly zip: DetectedType;
250
+ readonly docx: DetectedType;
251
+ readonly xlsx: DetectedType;
252
+ readonly pptx: DetectedType;
253
+ readonly odt: DetectedType;
254
+ readonly ods: DetectedType;
255
+ readonly odp: DetectedType;
256
+ readonly epub: DetectedType;
257
+ readonly jar: DetectedType;
258
+ readonly apk: DetectedType;
259
+ readonly ole: DetectedType;
260
+ readonly rtf: DetectedType;
261
+ readonly gzip: DetectedType;
262
+ readonly bzip2: DetectedType;
263
+ readonly xz: DetectedType;
264
+ readonly zstd: DetectedType;
265
+ readonly sevenZip: DetectedType;
266
+ readonly rar: DetectedType;
267
+ readonly tar: DetectedType;
268
+ readonly sqlite: DetectedType;
269
+ readonly woff: DetectedType;
270
+ readonly woff2: DetectedType;
271
+ readonly otf: DetectedType;
272
+ readonly ttf: DetectedType;
273
+ readonly exe: DetectedType;
274
+ readonly elf: DetectedType;
275
+ readonly macho: DetectedType;
276
+ readonly wasm: DetectedType;
277
+ readonly shortcut: DetectedType;
278
+ readonly script: DetectedType;
279
+ readonly html: DetectedType;
280
+ readonly xml: DetectedType;
281
+ readonly json: DetectedType;
282
+ readonly text: DetectedType;
283
+ };
284
+ /**
285
+ * The type of a file's content, from its leading bytes: never from its name or claimed type.
286
+ * Reads at most {@link FILE_SNIFF_BYTES}. `null` when the content is not a recognised type.
287
+ */
288
+ export declare function detectFileType(bytes: Uint8Array, options?: {
289
+ readonly complete?: boolean;
290
+ }): DetectedType | null;
291
+ //#endregion
292
+ //#region src/files/inspect.d.ts
293
+ interface InspectFileOptions {
294
+ /** The file's name. Default: `file.name`, for a `File`. */
295
+ readonly name?: string;
296
+ /** The type it claims. Default: `file.type`. Kept for reference only: never trusted. */
297
+ readonly declaredType?: string;
298
+ /** How {@link FileInspection.safeName} is made. */
299
+ readonly names?: SafeFileNameOptions;
300
+ }
301
+ /**
302
+ * What a file really is, and why it may be unsafe to accept: its type from its content (never
303
+ * its name or claimed type), whether that contradicts its extension, and its risks.
304
+ * Reads only the first {@link FILE_SNIFF_BYTES} bytes, so it is fast for any size. Server-safe.
305
+ *
306
+ * @throws {CopyFailure} `invalid-payload` when `file` is not a Blob.
307
+ */
308
+ export declare function inspectFile(file: Blob, options?: InspectFileOptions): Promise<FileInspection>;
309
+ //#endregion
310
+ export type { AcceptFilesOptions, AcceptFilesResult, AcceptedFile, DetectedType, FileFamily, FileInspection, FileRejectReason, FileRisk, FileSource, InspectFileOptions, RejectedFile, SafeFileNameOptions };
311
+ //# sourceMappingURL=files.d.ts.map