@c9up/archive 0.1.8 → 0.1.10

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/src/objects.ts CHANGED
@@ -37,6 +37,17 @@ export class DriveDirectory {
37
37
  * `DriveFile` but built on the in-package {@link StorageDriver} contract
38
38
  * (no router coupling — the legitimate ream divergence).
39
39
  */
40
+ /** A file described without its provider (flydrive `FileSnapshot`). */
41
+ export interface FileSnapshot {
42
+ key: string;
43
+ name: string;
44
+ contentLength: number;
45
+ /** ISO-8601 — a snapshot is meant to survive JSON. */
46
+ lastModified: string;
47
+ etag: string;
48
+ contentType?: string;
49
+ }
50
+
40
51
  export class DriveFile {
41
52
  isFile: true = true;
42
53
  isDirectory: false = false;
@@ -86,6 +97,35 @@ export class DriveFile {
86
97
  return this.#driver.url(this.key);
87
98
  }
88
99
 
100
+ /** Contents as bytes in an ArrayBuffer view — what a Blob or fetch body wants. */
101
+ getArrayBuffer(): Promise<Uint8Array> {
102
+ return this.#driver.getBytes(this.key);
103
+ }
104
+
105
+ /** A URL a client can upload TO, without going through the app. */
106
+ getSignedUploadUrl(options?: SignedUrlOptions): string | Promise<string> {
107
+ return this.#driver.getSignedUploadUrl(this.key, options);
108
+ }
109
+
110
+ /**
111
+ * A serializable description of this file (flydrive `toSnapshot`).
112
+ *
113
+ * Store it beside a record and rebuild the handle later with
114
+ * `disk.fromSnapshot(...)` — that avoids a round-trip to the provider just
115
+ * to render a name and a size.
116
+ */
117
+ async toSnapshot(): Promise<FileSnapshot> {
118
+ const metadata = await this.getMetaData();
119
+ return {
120
+ key: this.key,
121
+ name: this.name,
122
+ contentLength: metadata.contentLength,
123
+ lastModified: metadata.lastModified.toISOString(),
124
+ etag: metadata.etag,
125
+ contentType: metadata.contentType,
126
+ };
127
+ }
128
+
89
129
  getSignedUrl(options?: SignedUrlOptions): string | Promise<string> {
90
130
  return this.#driver.getSignedUrl(this.key, options);
91
131
  }
@@ -26,6 +26,15 @@ export function getStorage(): StorageManager | undefined {
26
26
 
27
27
  const storage: StorageManager = new Proxy({} as StorageManager, {
28
28
  get(_target, prop) {
29
+ // A module loader inspects what it imports before anyone uses it: it reads
30
+ // `then` to decide whether the namespace is thenable, and various symbols
31
+ // for interop and formatting. Throwing on those turns a plain
32
+ // `import { setX } from ".../services/main"` into a crash at import time,
33
+ // far from any real use. They are not members of what this stands in for,
34
+ // so answer undefined and let a genuine access be the one that reports.
35
+ if (typeof prop === "symbol" || prop === "then") {
36
+ return undefined;
37
+ }
29
38
  if (!instance) {
30
39
  throw new Error(
31
40
  "[archive] StorageManager singleton accessed before ArchiveProvider.boot() ran. " +
@@ -16,6 +16,7 @@
16
16
  import { AssertionError } from "node:assert";
17
17
  import { createHash } from "node:crypto";
18
18
  import { Readable } from "node:stream";
19
+ import type { Plugin, PluginApi, TestContext } from "@c9up/helix";
19
20
  import { ArchiveError } from "../errors.js";
20
21
  import {
21
22
  assertValidExpiry,
@@ -549,3 +550,53 @@ function extFromPath(filePath: string): string {
549
550
  const idx = filePath.lastIndexOf(".");
550
551
  return idx < 0 ? "" : filePath.slice(idx).toLowerCase();
551
552
  }
553
+
554
+ /** A drive that can enter/exit fake mode — structurally the `DriveManager`. */
555
+ export interface FakeableDrive {
556
+ /** Swap a disk for an in-memory fake and return it. */
557
+ fake(service?: string): FakeStorageManager;
558
+ /** Restore the real disk. */
559
+ restore(service?: string): void;
560
+ }
561
+
562
+ /**
563
+ * `driveFake()` — a helix plugin (AdonisJS `drive.fake()` parity) that injects
564
+ * an in-memory {@link FakeStorageManager} on the test context as `ctx.drive`,
565
+ * PER TEST, auto-restoring the real disk afterwards via `ctx.cleanup`:
566
+ *
567
+ * await configure({ plugins: [driveFake(drive)] });
568
+ * test("stores the avatar", async ({ drive }) => {
569
+ * await uploadAvatar();
570
+ * drive.assertExists("avatars/1.png");
571
+ * });
572
+ *
573
+ * Uses the manager's own `fake()`/`restore()` (the Adonis pattern); the
574
+ * getter+cleanup wiring adds the per-test lifecycle.
575
+ */
576
+ /** The slice of helix's `PluginApi` this plugin touches: the context getter. */
577
+ export type DriveHost = Pick<PluginApi, "context">;
578
+
579
+ /** The slice of the test context the getter reads: a cleanup hook. */
580
+ export type DriveContext = Pick<TestContext, "cleanup">;
581
+
582
+ export function driveFake(drive: FakeableDrive) {
583
+ // A wider parameter than `PluginApi` stays assignable to `Plugin`, so the
584
+ // plugin declares exactly what it touches and a caller can drive it with
585
+ // nothing more than that.
586
+ const plugin = (api: DriveHost): void => {
587
+ api.context.getter("drive", (ctx: DriveContext) => {
588
+ const fake = drive.fake();
589
+ ctx.cleanup(() => drive.restore());
590
+ return fake;
591
+ });
592
+ };
593
+ return plugin satisfies Plugin;
594
+ }
595
+
596
+ // Typing side of the plugin — importing `@c9up/archive/testing` augments the
597
+ // helix test context with `drive` (the Japa pattern).
598
+ declare module "@c9up/helix" {
599
+ interface TestContext {
600
+ drive: FakeStorageManager;
601
+ }
602
+ }