@c9up/archive 0.1.5 → 0.1.7

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.
Files changed (46) hide show
  1. package/dist/ArchiveProvider.d.ts +6 -0
  2. package/dist/ArchiveProvider.d.ts.map +1 -1
  3. package/dist/ArchiveProvider.js +33 -7
  4. package/dist/ArchiveProvider.js.map +1 -1
  5. package/dist/DriveManager.d.ts +80 -0
  6. package/dist/DriveManager.d.ts.map +1 -0
  7. package/dist/DriveManager.js +102 -0
  8. package/dist/DriveManager.js.map +1 -0
  9. package/dist/GcsDriver.d.ts +14 -4
  10. package/dist/GcsDriver.d.ts.map +1 -1
  11. package/dist/GcsDriver.js +126 -15
  12. package/dist/GcsDriver.js.map +1 -1
  13. package/dist/S3Driver.d.ts +14 -4
  14. package/dist/S3Driver.d.ts.map +1 -1
  15. package/dist/S3Driver.js +268 -15
  16. package/dist/S3Driver.js.map +1 -1
  17. package/dist/StorageManager.d.ts +128 -18
  18. package/dist/StorageManager.d.ts.map +1 -1
  19. package/dist/StorageManager.js +147 -13
  20. package/dist/StorageManager.js.map +1 -1
  21. package/dist/expiry.d.ts +7 -0
  22. package/dist/expiry.d.ts.map +1 -1
  23. package/dist/expiry.js +47 -0
  24. package/dist/expiry.js.map +1 -1
  25. package/dist/index.d.ts +20 -3
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +18 -2
  28. package/dist/index.js.map +1 -1
  29. package/dist/objects.d.ts +50 -0
  30. package/dist/objects.d.ts.map +1 -0
  31. package/dist/objects.js +77 -0
  32. package/dist/objects.js.map +1 -0
  33. package/dist/testing/FakeStorage.d.ts +43 -4
  34. package/dist/testing/FakeStorage.d.ts.map +1 -1
  35. package/dist/testing/FakeStorage.js +153 -12
  36. package/dist/testing/FakeStorage.js.map +1 -1
  37. package/package.json +2 -1
  38. package/src/ArchiveProvider.ts +49 -9
  39. package/src/DriveManager.ts +151 -0
  40. package/src/GcsDriver.ts +166 -15
  41. package/src/S3Driver.ts +317 -15
  42. package/src/StorageManager.ts +294 -25
  43. package/src/expiry.ts +52 -0
  44. package/src/index.ts +34 -2
  45. package/src/objects.ts +92 -0
  46. package/src/testing/FakeStorage.ts +191 -12
@@ -9,13 +9,63 @@ import * as fs from "node:fs";
9
9
  import * as path from "node:path";
10
10
  import { pipeline } from "node:stream/promises";
11
11
  import { ArchiveError } from "./errors.js";
12
- import { assertValidExpiry, DEFAULT_EXPIRES_IN } from "./expiry.js";
12
+ import {
13
+ assertValidExpiry,
14
+ DEFAULT_EXPIRES_IN,
15
+ parseExpiry,
16
+ } from "./expiry.js";
13
17
  import { inferMimeType } from "./mime-types.js";
18
+ import { DriveDirectory, DriveFile } from "./objects.js";
19
+
20
+ export { DriveDirectory, DriveFile } from "./objects.js";
14
21
 
15
22
  /** Options for {@link StorageDriver.getSignedUrl}. */
16
23
  export interface SignedUrlOptions {
17
- /** URL lifetime in seconds. Default: 300 (5 minutes). Bounds: 1–604800. */
18
- expiresIn?: number;
24
+ /**
25
+ * URL lifetime. Either a number of seconds or an AdonisJS-style
26
+ * duration string (`'30mins'`, `'7 days'`, `'1h'`). Default: 300
27
+ * (5 minutes). Bounds after parsing: 1–604800.
28
+ */
29
+ expiresIn?: number | string;
30
+ /** Sets the response `Content-Type` served with the signed URL (cloud drivers). */
31
+ contentType?: string;
32
+ /** Sets the response `Content-Disposition` served with the signed URL (cloud drivers). */
33
+ contentDisposition?: string;
34
+ }
35
+
36
+ /**
37
+ * Options accepted by the write operations (`put`/`putStream`) and by
38
+ * `copy`/`move`. AdonisJS Drive `WriteOptions` parity. Cloud drivers map
39
+ * these onto object metadata headers; the LocalDriver honours only
40
+ * `visibility` (the rest have no filesystem equivalent).
41
+ */
42
+ export interface WriteOptions {
43
+ /** Visibility to apply to the written / copied object. */
44
+ visibility?: Visibility;
45
+ /** `Content-Type` metadata. Falls back to extension-based inference. */
46
+ contentType?: string;
47
+ /** `Cache-Control` metadata (cloud drivers). */
48
+ cacheControl?: string;
49
+ /** `Content-Disposition` metadata (cloud drivers). */
50
+ contentDisposition?: string;
51
+ /** Declared byte length. Used by S3 to choose single-PUT vs multipart. */
52
+ contentLength?: number;
53
+ }
54
+
55
+ /** Result shape of {@link StorageDriver.listAll} — AdonisJS Drive parity. */
56
+ export interface ListAllResult {
57
+ /** Continuation token to fetch the next page (cloud drivers only). */
58
+ paginationToken?: string;
59
+ /** Files and (non-recursive only) directories under the prefix. */
60
+ objects: Iterable<DriveFile | DriveDirectory>;
61
+ }
62
+
63
+ /** Options accepted by {@link StorageDriver.listAll}. */
64
+ export interface ListAllOptions {
65
+ /** Recurse into sub-prefixes. When true, no directories are yielded. */
66
+ recursive?: boolean;
67
+ /** Continuation token from a previous page (cloud drivers only). */
68
+ paginationToken?: string;
19
69
  }
20
70
 
21
71
  /** Options for {@link StorageDriver.putStream}. */
@@ -55,9 +105,13 @@ export interface StorageEntry {
55
105
  export interface Metadata {
56
106
  /** Size in bytes. */
57
107
  size: number;
108
+ /** AdonisJS `ObjectMetaData` alias of {@link Metadata.size}. Same value. */
109
+ contentLength: number;
58
110
  /** Content type. Driver-inferred for Local (extension-based), server-
59
111
  * reported for S3. Falls back to `application/octet-stream`. */
60
112
  mimeType: string;
113
+ /** AdonisJS `ObjectMetaData` alias of {@link Metadata.mimeType}. Same value. */
114
+ contentType: string;
61
115
  /** Last-modified timestamp as a `Date` — not a string, not epoch ms. */
62
116
  lastModified: Date;
63
117
  /** Strong or weak ETag with surrounding quotes stripped. `W/` prefix
@@ -68,16 +122,20 @@ export interface Metadata {
68
122
  }
69
123
 
70
124
  /**
71
- * StorageDriver contract — frozen at v1.0 (Epic 43, 2026-05-05).
125
+ * StorageDriver contract — v1.1 (Epic 43, extended for AdonisJS Drive /
126
+ * flydrive parity 2026-07-06).
72
127
  *
73
128
  * Driver authors implement this interface verbatim. The interface is treated
74
- * as a stable contract: new methods are NOT added without a version-bump + a
75
- * 2-epic deprecation window. Optional fields are added in minor versions.
76
- * Method signatures never change in-place — a renamed method ships as a new
77
- * method + the old one delegating, deprecated for ≥1 epic.
129
+ * as a stable contract: methods are added only to track upstream Drive
130
+ * parity. Method signatures never change in-place — a renamed method ships as
131
+ * a new method + the old one delegating, deprecated for ≥1 epic.
78
132
  */
79
133
  export interface StorageDriver {
80
- put(filePath: string, content: Buffer | string): Promise<void>;
134
+ put(
135
+ filePath: string,
136
+ content: Buffer | string,
137
+ options?: WriteOptions,
138
+ ): Promise<void>;
81
139
  /**
82
140
  * Upload from a readable stream. Local pipes to disk; S3 uses
83
141
  * single-PUT if `contentLength ≤ 5 MiB`, otherwise multipart.
@@ -87,7 +145,22 @@ export interface StorageDriver {
87
145
  readable: NodeJS.ReadableStream,
88
146
  options?: PutStreamOptions,
89
147
  ): Promise<void>;
148
+ /**
149
+ * Raw contents as a `Buffer`, or `null` when the object is absent.
150
+ *
151
+ * DIVERGENCE from AdonisJS Drive (documented, deliberate): Adonis
152
+ * `get()` returns a UTF-8 `string` and throws on absence. Ream keeps
153
+ * the binary-safe `Buffer | null` shape as a superset. Use
154
+ * {@link StorageDriver.getBytes} for the Adonis-shaped, throw-on-
155
+ * absence accessor.
156
+ */
90
157
  get(filePath: string): Promise<Buffer | null>;
158
+ /**
159
+ * Contents as a `Uint8Array`. AdonisJS Drive parity. Throws
160
+ * `ARCHIVE_NOT_FOUND` when the object is absent (unlike {@link get},
161
+ * a byte accessor can't express absence as a value).
162
+ */
163
+ getBytes(filePath: string): Promise<Uint8Array>;
91
164
  /**
92
165
  * Download as a readable stream. Throws `ARCHIVE_NOT_FOUND` when
93
166
  * the object is missing — streams can't express absence as a value.
@@ -117,11 +190,26 @@ export interface StorageDriver {
117
190
  filePath: string,
118
191
  options?: SignedUrlOptions,
119
192
  ): string | Promise<string>;
193
+ /**
194
+ * Return a time-boxed URL that grants **write** (PUT) access, letting
195
+ * a client upload directly to the backend. AdonisJS Drive parity.
196
+ * Cloud-only — the LocalDriver has no presigned-upload equivalent and
197
+ * throws `ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED`.
198
+ */
199
+ getSignedUploadUrl(
200
+ filePath: string,
201
+ options?: SignedUrlOptions,
202
+ ): string | Promise<string>;
120
203
  /**
121
204
  * Resolve object metadata. Throws `ArchiveError('ARCHIVE_NOT_FOUND', ...)`
122
205
  * when the object does not exist.
123
206
  */
124
207
  getMetadata(filePath: string): Promise<Metadata>;
208
+ /**
209
+ * Resolve the `public` / `private` visibility of an object on its own,
210
+ * without a full metadata round-trip. AdonisJS Drive parity.
211
+ */
212
+ getVisibility(filePath: string): Promise<Visibility>;
125
213
  /**
126
214
  * Set `public` / `private` visibility. Idempotent — re-applying the
127
215
  * same visibility succeeds silently.
@@ -130,22 +218,36 @@ export interface StorageDriver {
130
218
  /**
131
219
  * Duplicate an object. Throws `ARCHIVE_NOT_FOUND` if `from` is
132
220
  * missing. Target is overwritten if it exists. Visibility is NOT
133
- * carried over — the new object takes default visibility.
221
+ * carried over unless `options.visibility` is passed — the new object
222
+ * takes default visibility.
134
223
  */
135
- copy(from: string, to: string): Promise<void>;
224
+ copy(from: string, to: string, options?: WriteOptions): Promise<void>;
136
225
  /**
137
226
  * Relocate an object. Equivalent to `copy` + `delete` on cloud
138
227
  * drivers (non-atomic between the two steps); atomic `rename` on
139
228
  * Local. Visibility IS preserved because identity is preserved.
140
229
  */
141
- move(from: string, to: string): Promise<void>;
230
+ move(from: string, to: string, options?: WriteOptions): Promise<void>;
231
+ /**
232
+ * Delete every object whose path starts with `prefix`. Local removes
233
+ * the matching files (and prunes emptied directories); S3 batch-deletes;
234
+ * GCS deletes per object. AdonisJS Drive parity.
235
+ */
236
+ deleteAll(prefix: string): Promise<void>;
142
237
  /**
143
238
  * Yield one {@link StorageEntry} per object whose path starts with
144
239
  * `prefix`. Pagination (S3/GCS) and filesystem walk (Local) happen
145
240
  * lazily — callers can `break` early and no further requests are
146
- * issued.
241
+ * issued. Ream superset — kept alongside the Adonis-shaped
242
+ * {@link StorageDriver.listAll}.
147
243
  */
148
244
  list(prefix: string): AsyncIterable<StorageEntry>;
245
+ /**
246
+ * AdonisJS Drive `listAll`: a single page of {@link DriveFile} (and,
247
+ * when non-recursive, {@link DriveDirectory}) entries plus an optional
248
+ * pagination token.
249
+ */
250
+ listAll(prefix: string, options?: ListAllOptions): Promise<ListAllResult>;
149
251
  }
150
252
 
151
253
  export interface LocalDriverOptions {
@@ -238,13 +340,34 @@ export class LocalDriver implements StorageDriver {
238
340
  return full;
239
341
  }
240
342
 
241
- async put(filePath: string, content: Buffer | string): Promise<void> {
343
+ async put(
344
+ filePath: string,
345
+ content: Buffer | string,
346
+ options?: WriteOptions,
347
+ ): Promise<void> {
242
348
  const full = this.#safePath(filePath);
243
349
  const dir = path.dirname(full);
244
350
  if (!fs.existsSync(dir)) {
245
351
  fs.mkdirSync(dir, { recursive: true });
246
352
  }
247
353
  fs.writeFileSync(full, content);
354
+ // Only `visibility` has a filesystem-equivalent (the sidecar).
355
+ // contentType/cacheControl/... have no local meaning.
356
+ if (options?.visibility !== undefined) {
357
+ await this.setVisibility(filePath, options.visibility);
358
+ }
359
+ }
360
+
361
+ async getBytes(filePath: string): Promise<Uint8Array> {
362
+ const buf = await this.get(filePath);
363
+ if (buf === null) {
364
+ throw new ArchiveError(
365
+ "ARCHIVE_NOT_FOUND",
366
+ `File does not exist at path '${filePath}'`,
367
+ { hint: "Confirm the path and that the file was put() first." },
368
+ );
369
+ }
370
+ return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
248
371
  }
249
372
 
250
373
  async putStream(
@@ -346,15 +469,22 @@ export class LocalDriver implements StorageDriver {
346
469
  const etagBody = createHash("sha1")
347
470
  .update(`${stat.ino}-${stat.size}-${stat.mtimeMs}`)
348
471
  .digest("hex");
472
+ const mimeType = inferMimeType(path.extname(filePath).toLowerCase());
349
473
  return {
350
474
  size: stat.size,
351
- mimeType: inferMimeType(path.extname(filePath).toLowerCase()),
475
+ contentLength: stat.size,
476
+ mimeType,
477
+ contentType: mimeType,
352
478
  lastModified: stat.mtime,
353
479
  etag: `W/"${etagBody}"`,
354
480
  visibility: this.#readVisibility(filePath),
355
481
  };
356
482
  }
357
483
 
484
+ async getVisibility(filePath: string): Promise<Visibility> {
485
+ return this.#readVisibility(filePath);
486
+ }
487
+
358
488
  async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
359
489
  const full = this.#safePath(filePath);
360
490
  if (!fs.existsSync(full)) {
@@ -412,7 +542,7 @@ export class LocalDriver implements StorageDriver {
412
542
  // can never be served — `storage.get()` would reject it later via
413
543
  // `#safePath`, but signing-time errors are easier to diagnose.
414
544
  this.#safePath(filePath);
415
- const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;
545
+ const expiresIn = parseExpiry(options?.expiresIn ?? DEFAULT_EXPIRES_IN);
416
546
  assertValidExpiry(expiresIn);
417
547
  const secret = this.#signingSecret;
418
548
  if (secret === null) {
@@ -433,6 +563,21 @@ export class LocalDriver implements StorageDriver {
433
563
  return `${this.publicUrl(filePath)}?exp=${exp}&sig=${sig}`;
434
564
  }
435
565
 
566
+ /**
567
+ * The LocalDriver serves uploads through the app (not a presigned
568
+ * PUT to an object store), so there is no presigned-upload URL to
569
+ * hand out. Fail loudly rather than return an unusable value.
570
+ */
571
+ getSignedUploadUrl(_filePath: string, _options?: SignedUrlOptions): string {
572
+ throw new ArchiveError(
573
+ "ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED",
574
+ "LocalDriver does not support presigned upload URLs",
575
+ {
576
+ hint: "Presigned uploads are an S3/GCS feature. For local storage, upload through your app's HTTP handler.",
577
+ },
578
+ );
579
+ }
580
+
436
581
  /**
437
582
  * @internal Used by the signed-route middleware to re-compute the
438
583
  * HMAC server-side. Not part of the public `StorageDriver` contract.
@@ -441,7 +586,7 @@ export class LocalDriver implements StorageDriver {
441
586
  return this.#signingSecret;
442
587
  }
443
588
 
444
- async copy(from: string, to: string): Promise<void> {
589
+ async copy(from: string, to: string, options?: WriteOptions): Promise<void> {
445
590
  const fromFull = this.#safePath(from);
446
591
  const toFull = this.#safePath(to);
447
592
  if (!fs.existsSync(fromFull)) {
@@ -455,10 +600,13 @@ export class LocalDriver implements StorageDriver {
455
600
  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
456
601
  fs.copyFileSync(fromFull, toFull);
457
602
  // Intentionally do NOT copy the visibility sidecar — new object
458
- // takes default visibility. Documented in the story spec.
603
+ // takes default visibility unless the caller asks otherwise.
604
+ if (options?.visibility !== undefined) {
605
+ await this.setVisibility(to, options.visibility);
606
+ }
459
607
  }
460
608
 
461
- async move(from: string, to: string): Promise<void> {
609
+ async move(from: string, to: string, options?: WriteOptions): Promise<void> {
462
610
  const fromFull = this.#safePath(from);
463
611
  const toFull = this.#safePath(to);
464
612
  if (!fs.existsSync(fromFull)) {
@@ -524,6 +672,83 @@ export class LocalDriver implements StorageDriver {
524
672
  }
525
673
  }
526
674
  }
675
+ // An explicit visibility override wins over the preserved value.
676
+ if (options?.visibility !== undefined) {
677
+ await this.setVisibility(to, options.visibility);
678
+ }
679
+ }
680
+
681
+ async deleteAll(prefix: string): Promise<void> {
682
+ // Walk the existing listing (already sidecar-aware + safe) and
683
+ // remove every match. delete() also drops each file's sidecar.
684
+ const paths: string[] = [];
685
+ for await (const entry of this.list(prefix)) {
686
+ paths.push(entry.path);
687
+ }
688
+ for (const p of paths) {
689
+ await this.delete(p);
690
+ }
691
+ // Prune the prefix directory itself when it is now empty, mirroring
692
+ // flydrive's "the folder is deleted" behaviour. Best-effort.
693
+ const dir = this.#safePath(prefix);
694
+ if (dir !== this.#root && fs.existsSync(dir)) {
695
+ try {
696
+ const stat = fs.statSync(dir);
697
+ if (stat.isDirectory() && fs.readdirSync(dir).length === 0) {
698
+ fs.rmdirSync(dir);
699
+ }
700
+ } catch {
701
+ // benign — leave non-empty / vanished dirs alone.
702
+ }
703
+ }
704
+ }
705
+
706
+ async listAll(
707
+ prefix: string,
708
+ options?: ListAllOptions,
709
+ ): Promise<ListAllResult> {
710
+ const recursive = options?.recursive ?? false;
711
+ const files: DriveFile[] = [];
712
+ const directories = new Map<string, DriveDirectory>();
713
+ const normalizedPrefix =
714
+ prefix === "" || prefix === "/"
715
+ ? ""
716
+ : prefix.endsWith("/")
717
+ ? prefix
718
+ : `${prefix}/`;
719
+ for await (const entry of this.list(normalizedPrefix)) {
720
+ if (recursive) {
721
+ files.push(new DriveFile(entry.path, this, this.#entryMetadata(entry)));
722
+ continue;
723
+ }
724
+ // Non-recursive: collapse anything below the immediate level
725
+ // into a DriveDirectory marker.
726
+ const rest = entry.path.slice(normalizedPrefix.length);
727
+ const slash = rest.indexOf("/");
728
+ if (slash === -1) {
729
+ files.push(new DriveFile(entry.path, this, this.#entryMetadata(entry)));
730
+ } else {
731
+ const dirPrefix = normalizedPrefix + rest.slice(0, slash);
732
+ if (!directories.has(dirPrefix)) {
733
+ directories.set(dirPrefix, new DriveDirectory(dirPrefix));
734
+ }
735
+ }
736
+ }
737
+ return { objects: [...directories.values(), ...files] };
738
+ }
739
+
740
+ /** Build a metadata snapshot from a cheap `list()` entry (no extra stat). */
741
+ #entryMetadata(entry: StorageEntry): Metadata {
742
+ const mimeType = inferMimeType(path.extname(entry.path).toLowerCase());
743
+ return {
744
+ size: entry.size,
745
+ contentLength: entry.size,
746
+ mimeType,
747
+ contentType: mimeType,
748
+ lastModified: entry.lastModified,
749
+ etag: "",
750
+ visibility: this.#readVisibility(entry.path),
751
+ };
527
752
  }
528
753
 
529
754
  async *list(prefix: string): AsyncIterable<StorageEntry> {
@@ -562,8 +787,12 @@ export class StorageManager {
562
787
  this.#driver = driver;
563
788
  }
564
789
 
565
- put(filePath: string, content: Buffer | string): Promise<void> {
566
- return this.#driver.put(filePath, content);
790
+ put(
791
+ filePath: string,
792
+ content: Buffer | string,
793
+ options?: WriteOptions,
794
+ ): Promise<void> {
795
+ return this.#driver.put(filePath, content, options);
567
796
  }
568
797
 
569
798
  putStream(
@@ -578,6 +807,16 @@ export class StorageManager {
578
807
  return this.#driver.get(filePath);
579
808
  }
580
809
 
810
+ /** Contents as a `Uint8Array`. Throws `ARCHIVE_NOT_FOUND` if absent. */
811
+ getBytes(filePath: string): Promise<Uint8Array> {
812
+ return this.#driver.getBytes(filePath);
813
+ }
814
+
815
+ /** @deprecated AdonisJS Drive alias — use {@link StorageManager.getBytes}. */
816
+ getArrayBuffer(filePath: string): Promise<Uint8Array> {
817
+ return this.#driver.getBytes(filePath);
818
+ }
819
+
581
820
  getStream(filePath: string): Promise<NodeJS.ReadableStream> {
582
821
  return this.#driver.getStream(filePath);
583
822
  }
@@ -594,6 +833,11 @@ export class StorageManager {
594
833
  return this.#driver.url(filePath);
595
834
  }
596
835
 
836
+ /** AdonisJS Drive name for {@link url}. */
837
+ getUrl(filePath: string): Promise<string> {
838
+ return this.#driver.url(filePath);
839
+ }
840
+
597
841
  publicUrl(filePath: string): string {
598
842
  return this.#driver.publicUrl(filePath);
599
843
  }
@@ -605,23 +849,48 @@ export class StorageManager {
605
849
  return this.#driver.getSignedUrl(filePath, options);
606
850
  }
607
851
 
852
+ getSignedUploadUrl(
853
+ filePath: string,
854
+ options?: SignedUrlOptions,
855
+ ): string | Promise<string> {
856
+ return this.#driver.getSignedUploadUrl(filePath, options);
857
+ }
858
+
608
859
  getMetadata(filePath: string): Promise<Metadata> {
609
860
  return this.#driver.getMetadata(filePath);
610
861
  }
611
862
 
863
+ /** AdonisJS Drive casing for {@link getMetadata}. */
864
+ getMetaData(filePath: string): Promise<Metadata> {
865
+ return this.#driver.getMetadata(filePath);
866
+ }
867
+
868
+ getVisibility(filePath: string): Promise<Visibility> {
869
+ return this.#driver.getVisibility(filePath);
870
+ }
871
+
612
872
  setVisibility(filePath: string, visibility: Visibility): Promise<void> {
613
873
  return this.#driver.setVisibility(filePath, visibility);
614
874
  }
615
875
 
616
- copy(from: string, to: string): Promise<void> {
617
- return this.#driver.copy(from, to);
876
+ copy(from: string, to: string, options?: WriteOptions): Promise<void> {
877
+ return this.#driver.copy(from, to, options);
878
+ }
879
+
880
+ move(from: string, to: string, options?: WriteOptions): Promise<void> {
881
+ return this.#driver.move(from, to, options);
618
882
  }
619
883
 
620
- move(from: string, to: string): Promise<void> {
621
- return this.#driver.move(from, to);
884
+ deleteAll(prefix: string): Promise<void> {
885
+ return this.#driver.deleteAll(prefix);
622
886
  }
623
887
 
624
888
  list(prefix: string): AsyncIterable<StorageEntry> {
625
889
  return this.#driver.list(prefix);
626
890
  }
891
+
892
+ /** AdonisJS Drive `listAll` — paged {@link DriveFile}/{@link DriveDirectory}. */
893
+ listAll(prefix: string, options?: ListAllOptions): Promise<ListAllResult> {
894
+ return this.#driver.listAll(prefix, options);
895
+ }
627
896
  }
package/src/expiry.ts CHANGED
@@ -12,6 +12,58 @@ export const DEFAULT_EXPIRES_IN = 300; // 5 minutes
12
12
  /** Maximum allowed expiry (AWS SigV4 cap). */
13
13
  export const MAX_EXPIRES_IN = 604_800; // 7 days
14
14
 
15
+ /**
16
+ * Multipliers (in seconds) for the human-friendly duration suffixes
17
+ * accepted by {@link parseExpiry}. Mirrors the units understood by
18
+ * AdonisJS Drive's `string.seconds.parse` helper.
19
+ */
20
+ const UNIT_SECONDS: Record<string, number> = {
21
+ s: 1,
22
+ sec: 1,
23
+ secs: 1,
24
+ second: 1,
25
+ seconds: 1,
26
+ m: 60,
27
+ min: 60,
28
+ mins: 60,
29
+ minute: 60,
30
+ minutes: 60,
31
+ h: 3600,
32
+ hr: 3600,
33
+ hrs: 3600,
34
+ hour: 3600,
35
+ hours: 3600,
36
+ d: 86_400,
37
+ day: 86_400,
38
+ days: 86_400,
39
+ w: 604_800,
40
+ week: 604_800,
41
+ weeks: 604_800,
42
+ };
43
+
44
+ /**
45
+ * Normalise a signed-URL `expiresIn` into a number of seconds. Accepts
46
+ * either a raw number of seconds (returned as-is) or a human-friendly
47
+ * duration string such as `'30mins'`, `'7 days'`, `'1h'` — AdonisJS
48
+ * Drive parity. Unrecognised strings throw `ARCHIVE_INVALID_EXPIRY`.
49
+ */
50
+ export function parseExpiry(expiresIn: number | string): number {
51
+ if (typeof expiresIn === "number") return expiresIn;
52
+ const match = /^\s*(\d+(?:\.\d+)?)\s*([a-z]*)\s*$/i.exec(expiresIn);
53
+ const unitKey = match?.[2]?.toLowerCase() ?? "";
54
+ const multiplier = unitKey === "" ? 1 : UNIT_SECONDS[unitKey];
55
+ if (match === undefined || match === null || multiplier === undefined) {
56
+ throw new ArchiveError(
57
+ "ARCHIVE_INVALID_EXPIRY",
58
+ `Signed-URL expiresIn string '${expiresIn}' could not be parsed`,
59
+ {
60
+ hint: "Use a number of seconds, or a duration like '30mins', '1h', '7 days'.",
61
+ },
62
+ );
63
+ }
64
+ return Math.round(Number.parseFloat(match[1]) * multiplier);
65
+ }
66
+
15
67
  /**
16
68
  * Reject non-finite, zero, negative, or out-of-range expiries. Throws
17
69
  * `ARCHIVE_INVALID_EXPIRY` so callers get a typed error with a hint.
package/src/index.ts CHANGED
@@ -4,17 +4,28 @@
4
4
  * Drivers:
5
5
  * - LocalDriver (filesystem)
6
6
  * - S3Driver (S3 / R2 / MinIO via SigV4)
7
+ * - GcsDriver (Google Cloud Storage)
7
8
  *
8
- * Plus a StaticMiddleware for serving files over HTTP and a
9
- * signed-route handler for serving HMAC-signed Local URLs.
9
+ * A `DriveManager` provides AdonisJS Drive-style multi-disk resolution
10
+ * (`use(name?)`), plus a `StaticMiddleware` for serving files over HTTP
11
+ * and a signed-route handler for serving HMAC-signed Local URLs.
10
12
  */
11
13
 
14
+ export type { ArchiveConfig } from "./ArchiveProvider.js";
15
+ export {
16
+ type DriveConfig,
17
+ DriveManager,
18
+ type DriveServiceFactory,
19
+ type FsServiceOptions,
20
+ services,
21
+ } from "./DriveManager.js";
12
22
  export { ArchiveError } from "./errors.js";
13
23
  export {
14
24
  type GcsConfig,
15
25
  GcsDriver,
16
26
  type GcsServiceAccount,
17
27
  } from "./GcsDriver.js";
28
+ export { DriveDirectory, DriveFile } from "./objects.js";
18
29
  export { type S3Config, S3Driver } from "./S3Driver.js";
19
30
  export {
20
31
  type StaticConfig,
@@ -23,6 +34,8 @@ export {
23
34
  type StaticMiddlewareResponse,
24
35
  } from "./StaticMiddleware.js";
25
36
  export {
37
+ type ListAllOptions,
38
+ type ListAllResult,
26
39
  LocalDriver,
27
40
  type LocalDriverOptions,
28
41
  type Metadata,
@@ -32,6 +45,7 @@ export {
32
45
  type StorageEntry,
33
46
  StorageManager,
34
47
  type Visibility,
48
+ type WriteOptions,
35
49
  } from "./StorageManager.js";
36
50
  export {
37
51
  createSignedRouteHandler,
@@ -39,3 +53,21 @@ export {
39
53
  type SignedRouteOptions,
40
54
  type SignedRouteResponse,
41
55
  } from "./signed-route.js";
56
+
57
+ import type { ArchiveConfig } from "./ArchiveProvider.js";
58
+ import type { DriveConfig } from "./DriveManager.js";
59
+
60
+ /**
61
+ * Author-time config helper for `config/archive.ts` — AdonisJS Drive
62
+ * `defineConfig` parity. Identity at runtime; the generic preserves
63
+ * literal types for inference.
64
+ *
65
+ * Accepts the multi-disk shape `{ default, services, fakes }` (build the
66
+ * services with the `services.*` helpers) or the legacy single-disk
67
+ * `{ driver, local, s3, gcs }` shape.
68
+ */
69
+ export function defineConfig<T extends DriveConfig | ArchiveConfig>(
70
+ config: T,
71
+ ): T {
72
+ return config;
73
+ }