1 | // Type definitions for File System API
|
2 | // Project: http://www.w3.org/TR/file-system-api/
|
3 | // Definitions by: Kon <http://phyzkit.net/>
|
4 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
5 |
|
6 | /// <reference types="filewriter" />
|
7 |
|
8 | interface LocalFileSystem {
|
9 |
|
10 | /**
|
11 | * Used for storage with no guarantee of persistence.
|
12 | */
|
13 | TEMPORARY: number;
|
14 |
|
15 | /**
|
16 | * Used for storage that should not be removed by the user agent without application or user permission.
|
17 | */
|
18 | PERSISTENT: number;
|
19 |
|
20 | /**
|
21 | * Requests a filesystem in which to store application data.
|
22 | * @param type Whether the filesystem requested should be persistent, as defined above. Use one of TEMPORARY or PERSISTENT.
|
23 | * @param size This is an indicator of how much storage space, in bytes, the application expects to need.
|
24 | * @param successCallback The callback that is called when the user agent provides a filesystem.
|
25 | * @param errorCallback A callback that is called when errors happen, or when the request to obtain the filesystem is denied.
|
26 | */
|
27 | requestFileSystem(type: number, size: number, successCallback: FileSystemCallback, errorCallback?: ErrorCallback): void;
|
28 |
|
29 | /**
|
30 | * Allows the user to look up the Entry for a file or directory referred to by a local URL.
|
31 | * @param url A URL referring to a local file in a filesystem accessable via this API.
|
32 | * @param successCallback A callback that is called to report the Entry to which the supplied URL refers.
|
33 | * @param errorCallback A callback that is called when errors happen, or when the request to obtain the Entry is denied.
|
34 | */
|
35 | resolveLocalFileSystemURL(url: string, successCallback: EntryCallback, errorCallback?: ErrorCallback): void;
|
36 |
|
37 | /**
|
38 | * see requestFileSystem.
|
39 | */
|
40 | webkitRequestFileSystem(type: number, size: number, successCallback: FileSystemCallback, errorCallback?: ErrorCallback): void;
|
41 | }
|
42 |
|
43 | interface LocalFileSystemSync {
|
44 | /**
|
45 | * Used for storage with no guarantee of persistence.
|
46 | */
|
47 | TEMPORARY: number;
|
48 |
|
49 | /**
|
50 | * Used for storage that should not be removed by the user agent without application or user permission.
|
51 | */
|
52 | PERSISTENT: number;
|
53 |
|
54 | /**
|
55 | * Requests a filesystem in which to store application data.
|
56 | * @param type Whether the filesystem requested should be persistent, as defined above. Use one of TEMPORARY or PERSISTENT.
|
57 | * @param size This is an indicator of how much storage space, in bytes, the application expects to need.
|
58 | */
|
59 | requestFileSystemSync(type: number, size: number): FileSystemSync;
|
60 |
|
61 | /**
|
62 | * Allows the user to look up the Entry for a file or directory referred to by a local URL.
|
63 | * @param url A URL referring to a local file in a filesystem accessable via this API.
|
64 | */
|
65 | resolveLocalFileSystemSyncURL(url: string): EntrySync;
|
66 |
|
67 | /**
|
68 | * see requestFileSystemSync
|
69 | */
|
70 | webkitRequestFileSystemSync(type: number, size: number): FileSystemSync;
|
71 | }
|
72 |
|
73 | interface Metadata {
|
74 | /**
|
75 | * This is the time at which the file or directory was last modified.
|
76 | */
|
77 | modificationTime: Date;
|
78 |
|
79 | /**
|
80 | * The size of the file, in bytes. This must return 0 for directories.
|
81 | */
|
82 | size: number;
|
83 | }
|
84 |
|
85 | interface Flags {
|
86 | /**
|
87 | * Used to indicate that the user wants to create a file or directory if it was not previously there.
|
88 | */
|
89 | create?: boolean | undefined;
|
90 |
|
91 | /**
|
92 | * By itself, exclusive must have no effect. Used with create, it must cause getFile and getDirectory to fail if the target path already exists.
|
93 | */
|
94 | exclusive?: boolean | undefined;
|
95 | }
|
96 |
|
97 | /**
|
98 | * This interface represents a file system.
|
99 | */
|
100 | interface FileSystem {
|
101 | /**
|
102 | * This is the name of the file system. The specifics of naming filesystems is unspecified, but a name must be unique across the list of exposed file systems.
|
103 | */
|
104 | readonly name: string;
|
105 |
|
106 | /**
|
107 | * The root directory of the file system.
|
108 | */
|
109 | readonly root: FileSystemDirectoryEntry;
|
110 | }
|
111 |
|
112 | interface FileSystemEntry {
|
113 |
|
114 | /**
|
115 | * Entry is a file.
|
116 | */
|
117 | readonly isFile: boolean;
|
118 |
|
119 | /**
|
120 | * Entry is a directory.
|
121 | */
|
122 | readonly isDirectory: boolean;
|
123 |
|
124 | /**
|
125 | * Look up metadata about this entry.
|
126 | * @param successCallback A callback that is called with the time of the last modification.
|
127 | * @param errorCallback ErrorCallback A callback that is called when errors happen.
|
128 | */
|
129 | getMetadata(successCallback: MetadataCallback, errorCallback?: ErrorCallback): void;
|
130 |
|
131 | /**
|
132 | * The name of the entry, excluding the path leading to it.
|
133 | */
|
134 | readonly name: string;
|
135 |
|
136 | /**
|
137 | * The full absolute path from the root to the entry.
|
138 | */
|
139 | readonly fullPath: string;
|
140 |
|
141 | /**
|
142 | * The file system on which the entry resides.
|
143 | */
|
144 | readonly filesystem: FileSystem;
|
145 |
|
146 | /**
|
147 | * Move an entry to a different location on the file system. It is an error to try to:
|
148 | *
|
149 | * <ui>
|
150 | * <li>move a directory inside itself or to any child at any depth;</li>
|
151 | * <li>move an entry into its parent if a name different from its current one isn't provided;</li>
|
152 | * <li>move a file to a path occupied by a directory;</li>
|
153 | * <li>move a directory to a path occupied by a file;</li>
|
154 | * <li>move any element to a path occupied by a directory which is not empty.</li>
|
155 | * <ul>
|
156 | *
|
157 | * A move of a file on top of an existing file must attempt to delete and replace that file.
|
158 | * A move of a directory on top of an existing empty directory must attempt to delete and replace that directory.
|
159 | */
|
160 | moveTo(parent: FileSystemDirectoryEntry, newName?: string, successCallback?: EntryCallback, errorCallback?: ErrorCallback): void;
|
161 |
|
162 | /**
|
163 | * Copy an entry to a different location on the file system. It is an error to try to:
|
164 | *
|
165 | * <ul>
|
166 | * <li> copy a directory inside itself or to any child at any depth;</li>
|
167 | * <li> copy an entry into its parent if a name different from its current one isn't provided;</li>
|
168 | * <li> copy a file to a path occupied by a directory;</li>
|
169 | * <li> copy a directory to a path occupied by a file;</li>
|
170 | * <li> copy any element to a path occupied by a directory which is not empty.</li>
|
171 | * <li> A copy of a file on top of an existing file must attempt to delete and replace that file.</li>
|
172 | * <li> A copy of a directory on top of an existing empty directory must attempt to delete and replace that directory.</li>
|
173 | * </ul>
|
174 | *
|
175 | * Directory copies are always recursive--that is, they copy all contents of the directory.
|
176 | */
|
177 | copyTo(parent: FileSystemDirectoryEntry, newName?: string, successCallback?: EntryCallback, errorCallback?: ErrorCallback): void;
|
178 |
|
179 | /**
|
180 | * Returns a URL that can be used to identify this entry. Unlike the URN defined in [FILE-API-ED], it has no specific expiration; as it describes a location on disk, it should be valid at least as long as that location exists.
|
181 | */
|
182 | toURL(): string;
|
183 |
|
184 | /**
|
185 | * Deletes a file or directory. It is an error to attempt to delete a directory that is not empty. It is an error to attempt to delete the root directory of a filesystem.
|
186 | * @param successCallback A callback that is called on success.
|
187 | * @param errorCallback A callback that is called when errors happen.
|
188 | */
|
189 | remove(successCallback: VoidCallback, errorCallback?: ErrorCallback): void;
|
190 |
|
191 | /**
|
192 | * Look up the parent DirectoryEntry containing this Entry. If this Entry is the root of its filesystem, its parent is itself.
|
193 | * @param successCallback A callback that is called to return the parent Entry.
|
194 | * @param errorCallback A callback that is called when errors happen.
|
195 | */
|
196 | getParent(successCallback: DirectoryEntryCallback, errorCallback?: ErrorCallback): void;
|
197 | }
|
198 |
|
199 | /** Alias provided for backward compatibility */
|
200 | type Entry = FileSystemEntry;
|
201 |
|
202 | /**
|
203 | * This interface represents a directory on a file system.
|
204 | */
|
205 | interface FileSystemDirectoryEntry extends FileSystemEntry {
|
206 | /**
|
207 | * Creates a new DirectoryReader to read Entries from this Directory.
|
208 | */
|
209 | createReader(): DirectoryReader;
|
210 |
|
211 | /**
|
212 | * Creates or looks up a file.
|
213 | * @param path Either an absolute path or a relative path from this DirectoryEntry to the file to be looked up or created. It is an error to attempt to create a file whose immediate parent does not yet exist.
|
214 | * @param options
|
215 | * <ul>
|
216 | * <li>If create and exclusive are both true, and the path already exists, getFile must fail.</li>
|
217 | * <li>If create is true, the path doesn't exist, and no other error occurs, getFile must create it as a zero-length file and return a corresponding FileEntry.</li>
|
218 | * <li>If create is not true and the path doesn't exist, getFile must fail.</li>
|
219 | * <li>If create is not true and the path exists, but is a directory, getFile must fail.</li>
|
220 | * <li>Otherwise, if no other error occurs, getFile must return a FileEntry corresponding to path.</li>
|
221 | * </ul>
|
222 | * @param successCallback A callback that is called to return the File selected or created.
|
223 | * @param errorCallback A callback that is called when errors happen.
|
224 | */
|
225 | getFile(path: string, options?: Flags, successCallback?: FileEntryCallback, errorCallback?: ErrorCallback): void;
|
226 |
|
227 | /**
|
228 | * Creates or looks up a directory.
|
229 | * @param path Either an absolute path or a relative path from this DirectoryEntry to the directory to be looked up or created. It is an error to attempt to create a directory whose immediate parent does not yet exist.
|
230 | * @param options
|
231 | * <ul>
|
232 | * <li>If create and exclusive are both true and the path already exists, getDirectory must fail.</li>
|
233 | * <li>If create is true, the path doesn't exist, and no other error occurs, getDirectory must create and return a corresponding DirectoryEntry.</li>
|
234 | * <li>If create is not true and the path doesn't exist, getDirectory must fail.</li>
|
235 | * <li>If create is not true and the path exists, but is a file, getDirectory must fail.</li>
|
236 | * <li>Otherwise, if no other error occurs, getDirectory must return a DirectoryEntry corresponding to path.</li>
|
237 | * </ul>
|
238 | * @param successCallback A callback that is called to return the DirectoryEntry selected or created.
|
239 | * @param errorCallback A callback that is called when errors happen.
|
240 | *
|
241 | */
|
242 | getDirectory(path: string, options?: Flags, successCallback?: DirectoryEntryCallback, errorCallback?: ErrorCallback): void;
|
243 |
|
244 | /**
|
245 | * Deletes a directory and all of its contents, if any. In the event of an error [e.g. trying to delete a directory that contains a file that cannot be removed], some of the contents of the directory may be deleted. It is an error to attempt to delete the root directory of a filesystem.
|
246 | * @param successCallback A callback that is called on success.
|
247 | * @param errorCallback A callback that is called when errors happen.
|
248 | */
|
249 | removeRecursively(successCallback: VoidCallback, errorCallback?: ErrorCallback): void;
|
250 | }
|
251 |
|
252 | /** Alias provided for backward compatibility */
|
253 | type DirectoryEntry = FileSystemDirectoryEntry;
|
254 |
|
255 | /**
|
256 | * This interface lets a user list files and directories in a directory. If there are no additions to or deletions from a directory between the first and last call to readEntries, and no errors occur, then:
|
257 | * <ul>
|
258 | * <li> A series of calls to readEntries must return each entry in the directory exactly once.</li>
|
259 | * <li> Once all entries have been returned, the next call to readEntries must produce an empty array.</li>
|
260 | * <li> If not all entries have been returned, the array produced by readEntries must not be empty.</li>
|
261 | * <li> The entries produced by readEntries must not include the directory itself ["."] or its parent [".."].</li>
|
262 | * </ul>
|
263 | */
|
264 | interface DirectoryReader {
|
265 | /**
|
266 | * Read the next block of entries from this directory.
|
267 | * @param successCallback Called once per successful call to readEntries to deliver the next previously-unreported set of Entries in the associated Directory. If all Entries have already been returned from previous invocations of readEntries, successCallback must be called with a zero-length array as an argument.
|
268 | * @param errorCallback A callback indicating that there was an error reading from the Directory.
|
269 | */
|
270 | readEntries(successCallback: EntriesCallback, errorCallback?: ErrorCallback): void;
|
271 | }
|
272 |
|
273 | /**
|
274 | * This interface represents a file on a file system.
|
275 | */
|
276 | interface FileEntry extends FileSystemEntry {
|
277 | /**
|
278 | * Creates a new FileWriter associated with the file that this FileEntry represents.
|
279 | * @param successCallback A callback that is called with the new FileWriter.
|
280 | * @param errorCallback A callback that is called when errors happen.
|
281 | */
|
282 | createWriter(successCallback: FileWriterCallback, errorCallback?: ErrorCallback): void;
|
283 |
|
284 | /**
|
285 | * Returns a File that represents the current state of the file that this FileEntry represents.
|
286 | * @param successCallback A callback that is called with the File.
|
287 | * @param errorCallback A callback that is called when errors happen.
|
288 | */
|
289 | file(successCallback: FileCallback, errorCallback?: ErrorCallback): void;
|
290 | }
|
291 |
|
292 | /**
|
293 | * When requestFileSystem() succeeds, the following callback is made.
|
294 | */
|
295 | interface FileSystemCallback {
|
296 | /**
|
297 | * @param filesystem The file systems to which the app is granted access.
|
298 | */
|
299 | (filesystem: FileSystem): void;
|
300 | }
|
301 |
|
302 | /**
|
303 | * This interface is the callback used to look up Entry objects.
|
304 | */
|
305 | interface EntryCallback {
|
306 | /**
|
307 | * @param entry
|
308 | */
|
309 | (entry: FileSystemEntry): void;
|
310 | }
|
311 |
|
312 | /**
|
313 | * This interface is the callback used to look up FileEntry objects.
|
314 | */
|
315 | interface FileEntryCallback {
|
316 | /**
|
317 | * @param entry
|
318 | */
|
319 | (entry: FileEntry): void;
|
320 | }
|
321 |
|
322 | /**
|
323 | * This interface is the callback used to look up DirectoryEntry objects.
|
324 | */
|
325 | interface DirectoryEntryCallback {
|
326 | /**
|
327 | * @param entry
|
328 | */
|
329 | (entry: FileSystemDirectoryEntry): void;
|
330 | }
|
331 |
|
332 | /**
|
333 | * When readEntries() succeeds, the following callback is made.
|
334 | */
|
335 | interface EntriesCallback {
|
336 | (entries: FileSystemEntry[]): void;
|
337 | }
|
338 |
|
339 | /**
|
340 | * This interface is the callback used to look up file and directory metadata.
|
341 | */
|
342 | interface MetadataCallback {
|
343 | (metadata: Metadata): void;
|
344 | }
|
345 |
|
346 | /**
|
347 | * This interface is the callback used to create a FileWriter.
|
348 | */
|
349 | interface FileWriterCallback {
|
350 | (fileWriter: FileWriter): void;
|
351 | }
|
352 |
|
353 | /**
|
354 | * This interface is the callback used to obtain a File.
|
355 | */
|
356 | interface FileCallback {
|
357 | (file: File): void;
|
358 | }
|
359 |
|
360 | /**
|
361 | * This interface is the generic callback used to indicate success of an asynchronous method.
|
362 | */
|
363 | interface VoidCallback {
|
364 | (): void;
|
365 | }
|
366 |
|
367 | /**
|
368 | * When an error occurs, the following callback is made.
|
369 | */
|
370 | interface ErrorCallback {
|
371 | (err: Error): void;
|
372 | }
|
373 |
|
374 |
|
375 | /**
|
376 | * This interface represents a file system.
|
377 | */
|
378 | interface FileSystemSync {
|
379 | /**
|
380 | * This is the name of the file system. The specifics of naming filesystems is unspecified, but a name must be unique across the list of exposed file systems.
|
381 | */
|
382 | name: string;
|
383 |
|
384 | /**
|
385 | * root The root directory of the file system.
|
386 | */
|
387 | root: DirectoryEntrySync;
|
388 | }
|
389 |
|
390 | /**
|
391 | * An abstract interface representing entries in a file system, each of which may be a FileEntrySync or DirectoryEntrySync.
|
392 | */
|
393 | interface EntrySync {
|
394 | /**
|
395 | * EntrySync is a file.
|
396 | */
|
397 | isFile: boolean;
|
398 |
|
399 | /**
|
400 | * EntrySync is a directory.
|
401 | */
|
402 | isDirectory: boolean;
|
403 |
|
404 | /**
|
405 | * Look up metadata about this entry.
|
406 | */
|
407 | getMetadata(): Metadata;
|
408 |
|
409 | /**
|
410 | * The name of the entry, excluding the path leading to it.
|
411 | */
|
412 | name: string;
|
413 |
|
414 | /**
|
415 | * The full absolute path from the root to the entry.
|
416 | */
|
417 | fullPath: string;
|
418 |
|
419 | /**
|
420 | * The file system on which the entry resides.
|
421 | */
|
422 | filesystem: FileSystemSync;
|
423 |
|
424 | /**
|
425 | * Move an entry to a different location on the file system. It is an error to try to:
|
426 | * <ul>
|
427 | * <li> move a directory inside itself or to any child at any depth;</li>
|
428 | * <li> move an entry into its parent if a name different from its current one isn't provided;</li>
|
429 | * <li> move a file to a path occupied by a directory;</li>
|
430 | * <li> move a directory to a path occupied by a file;</li>
|
431 | * <li> move any element to a path occupied by a directory which is not empty.</li>
|
432 | * </ui>
|
433 | * A move of a file on top of an existing file must attempt to delete and replace that file. A move of a directory on top of an existing empty directory must attempt to delete and replace that directory.
|
434 | * @param parent The directory to which to move the entry.
|
435 | * @param newName The new name of the entry. Defaults to the EntrySync's current name if unspecified.
|
436 | */
|
437 | moveTo(parent: DirectoryEntrySync, newName?: string): EntrySync;
|
438 |
|
439 | /**
|
440 | * Copy an entry to a different location on the file system. It is an error to try to:
|
441 | * <ul>
|
442 | * <li> copy a directory inside itself or to any child at any depth;</li>
|
443 | * <li> copy an entry into its parent if a name different from its current one isn't provided;</li>
|
444 | * <li> copy a file to a path occupied by a directory;</li>
|
445 | * <li> copy a directory to a path occupied by a file;</li>
|
446 | * <li> copy any element to a path occupied by a directory which is not empty.</li>
|
447 | * </ui>
|
448 | * A copy of a file on top of an existing file must attempt to delete and replace that file.
|
449 | * A copy of a directory on top of an existing empty directory must attempt to delete and replace that directory.
|
450 | * Directory copies are always recursive--that is, they copy all contents of the directory.
|
451 | */
|
452 | copyTo(parent: DirectoryEntrySync, newName?: string): EntrySync;
|
453 |
|
454 | /**
|
455 | * Returns a URL that can be used to identify this entry. Unlike the URN defined in [FILE-API-ED], it has no specific expiration; as it describes a location on disk, it should be valid at least as long as that location exists.
|
456 | */
|
457 | toURL(): string;
|
458 |
|
459 | /**
|
460 | * Deletes a file or directory. It is an error to attempt to delete a directory that is not empty. It is an error to attempt to delete the root directory of a filesystem.
|
461 | */
|
462 | remove(): void;
|
463 |
|
464 | /**
|
465 | * Look up the parent DirectoryEntrySync containing this Entry. If this EntrySync is the root of its filesystem, its parent is itself.
|
466 | */
|
467 | getParent(): DirectoryEntrySync;
|
468 | }
|
469 |
|
470 | /**
|
471 | * This interface represents a directory on a file system.
|
472 | */
|
473 | interface DirectoryEntrySync extends EntrySync {
|
474 | /**
|
475 | * Creates a new DirectoryReaderSync to read EntrySyncs from this DirectorySync.
|
476 | */
|
477 | createReader(): DirectoryReaderSync;
|
478 |
|
479 | /**
|
480 | * Creates or looks up a directory.
|
481 | * @param path Either an absolute path or a relative path from this DirectoryEntrySync to the file to be looked up or created. It is an error to attempt to create a file whose immediate parent does not yet exist.
|
482 | * @param options
|
483 | * <ul>
|
484 | * <li> If create and exclusive are both true and the path already exists, getFile must fail.</li>
|
485 | * <li> If create is true, the path doesn't exist, and no other error occurs, getFile must create it as a zero-length file and return a corresponding FileEntry.</li>
|
486 | * <li> If create is not true and the path doesn't exist, getFile must fail.</li>
|
487 | * <li> If create is not true and the path exists, but is a directory, getFile must fail.</li>
|
488 | * <li> Otherwise, if no other error occurs, getFile must return a FileEntrySync corresponding to path.</li>
|
489 | * </ul>
|
490 | */
|
491 | getFile(path: string, options?: Flags): FileEntrySync;
|
492 |
|
493 | /**
|
494 | * Creates or looks up a directory.
|
495 | * @param path Either an absolute path or a relative path from this DirectoryEntrySync to the directory to be looked up or created. It is an error to attempt to create a directory whose immediate parent does not yet exist.
|
496 | * @param options
|
497 | * <ul>
|
498 | * <li> If create and exclusive are both true and the path already exists, getDirectory must fail.</li>
|
499 | * <li> If create is true, the path doesn't exist, and no other error occurs, getDirectory must create and return a corresponding DirectoryEntry.</li>
|
500 | * <li> If create is not true and the path doesn't exist, getDirectory must fail.</li>
|
501 | * <li> If create is not true and the path exists, but is a file, getDirectory must fail.</li>
|
502 | * <li> Otherwise, if no other error occurs, getDirectory must return a DirectoryEntrySync corresponding to path.</li>
|
503 | * </ul>
|
504 | */
|
505 | getDirectory(path: string, options?: Flags): DirectoryEntrySync;
|
506 |
|
507 | /**
|
508 | * Deletes a directory and all of its contents, if any. In the event of an error [e.g. trying to delete a directory that contains a file that cannot be removed], some of the contents of the directory may be deleted. It is an error to attempt to delete the root directory of a filesystem.
|
509 | */
|
510 | removeRecursively(): void;
|
511 | }
|
512 |
|
513 | /**
|
514 | * This interface lets a user list files and directories in a directory. If there are no additions to or deletions from a directory between the first and last call to readEntries, and no errors occur, then:
|
515 | * <ul>
|
516 | * <li> A series of calls to readEntries must return each entry in the directory exactly once.</li>
|
517 | * <li> Once all entries have been returned, the next call to readEntries must produce an empty array.</li>
|
518 | * <li> If not all entries have been returned, the array produced by readEntries must not be empty.</li>
|
519 | * <li> The entries produced by readEntries must not include the directory itself ["."] or its parent [".."].</li>
|
520 | * </ul>
|
521 | */
|
522 | interface DirectoryReaderSync {
|
523 | /**
|
524 | * Read the next block of entries from this directory.
|
525 | */
|
526 | readEntries(): EntrySync[];
|
527 | }
|
528 |
|
529 | /**
|
530 | * This interface represents a file on a file system.
|
531 | */
|
532 | interface FileEntrySync extends EntrySync {
|
533 | /**
|
534 | * Creates a new FileWriterSync associated with the file that this FileEntrySync represents.
|
535 | */
|
536 | createWriter(): FileWriterSync;
|
537 |
|
538 | /**
|
539 | * Returns a File that represents the current state of the file that this FileEntrySync represents.
|
540 | */
|
541 | file(): File;
|
542 | }
|
543 |
|
544 | interface Window extends LocalFileSystem, LocalFileSystemSync {
|
545 | }
|
546 |
|
547 | interface WorkerGlobalScope extends LocalFileSystem, LocalFileSystemSync {
|
548 | }
|