@guren/plugin-cloudflare 0.3.1 → 0.4.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/dist/index.d.ts CHANGED
@@ -1,16 +1,17 @@
1
- import { StorageDriver, PutOptions, FileMetadata, ServiceProviderConstructor } from '@guren/core';
2
- import { PathLike } from '@guren/core/internal/deploy-build';
3
-
1
+ import { FileMetadata, PutOptions, ServiceProviderConstructor, StorageDriver } from "@guren/core";
2
+ import { PathLike } from "@guren/core/internal/deploy-build";
3
+ //#region src/env.d.ts
4
4
  /** First call wins; later calls are ignored (never overwrite a live env). */
5
5
  declare function captureWorkersEnv(env: unknown): void;
6
6
  /** Throws with a clear message if called before the first request captured env. */
7
7
  declare function getWorkersEnv<E = unknown>(): E;
8
8
  /** Clears the holder. Used by createWorkersHandler on boot failure and by tests. */
9
9
  declare function resetWorkersEnv(): void;
10
-
10
+ //#endregion
11
+ //#region src/handler.d.ts
11
12
  interface WorkersExecutionContext {
12
- waitUntil(promise: Promise<unknown>): void;
13
- passThroughOnException?(): void;
13
+ waitUntil(promise: Promise<unknown>): void;
14
+ passThroughOnException?(): void;
14
15
  }
15
16
  /**
16
17
  * The shape `createWorkersHandler` needs from an app. Structural rather than
@@ -18,31 +19,32 @@ interface WorkersExecutionContext {
18
19
  * handler dedupes boot across its own requests for anything conforming here.
19
20
  */
20
21
  interface WorkersAppLike {
21
- boot(): Promise<void>;
22
- fetch(request: Request, env?: unknown, executionCtx?: unknown): Response | Promise<Response>;
22
+ boot(): Promise<void>;
23
+ fetch(request: Request, env?: unknown, executionCtx?: unknown): Response | Promise<Response>;
23
24
  }
24
25
  interface WorkersHandler {
25
- fetch(request: Request, env: unknown, ctx: WorkersExecutionContext): Promise<Response>;
26
+ fetch(request: Request, env: unknown, ctx: WorkersExecutionContext): Promise<Response>;
26
27
  }
27
28
  declare function createWorkersHandler(app: WorkersAppLike): WorkersHandler;
28
-
29
+ //#endregion
30
+ //#region src/build.d.ts
29
31
  interface BuildCloudflareOutputOptions {
30
- /** App root directory. Defaults to the current working directory. */
31
- rootDir?: PathLike;
32
- /** Output directory for the assembled worker. Defaults to `<root>/.cloudflare`. */
33
- outputDir?: PathLike;
34
- /** Module that default-exports the Guren Application. Defaults to `<root>/src/app.ts`. */
35
- appEntry?: PathLike;
36
- /** Static files directory copied into Workers Static Assets. Defaults to `<root>/public`. */
37
- publicDir?: PathLike;
38
- /** Vite SSR build output. Defaults to `<root>/.guren/ssr`. */
39
- ssrDir?: PathLike;
40
- /** Client manifest key for the frontend entry. Defaults to `resources/js/app.tsx`. */
41
- clientEntryKey?: string;
42
- /** SSR manifest key for the server entry. Defaults to `resources/js/ssr.tsx`. */
43
- ssrEntryKey?: string;
44
- /** Skip running the app's `build` script before assembling output. */
45
- skipAppBuild?: boolean;
32
+ /** App root directory. Defaults to the current working directory. */
33
+ rootDir?: PathLike;
34
+ /** Output directory for the assembled worker. Defaults to `<root>/.cloudflare`. */
35
+ outputDir?: PathLike;
36
+ /** Module that default-exports the Guren Application. Defaults to `<root>/src/app.ts`. */
37
+ appEntry?: PathLike;
38
+ /** Static files directory copied into Workers Static Assets. Defaults to `<root>/public`. */
39
+ publicDir?: PathLike;
40
+ /** Vite SSR build output. Defaults to `<root>/.guren/ssr`. */
41
+ ssrDir?: PathLike;
42
+ /** Client manifest key for the frontend entry. Defaults to `resources/js/app.tsx`. */
43
+ clientEntryKey?: string;
44
+ /** SSR manifest key for the server entry. Defaults to `resources/js/ssr.tsx`. */
45
+ ssrEntryKey?: string;
46
+ /** Skip running the app's `build` script before assembling output. */
47
+ skipAppBuild?: boolean;
46
48
  }
47
49
  /**
48
50
  * Assemble a deployable Cloudflare Workers directory (`.cloudflare/`) from a
@@ -60,7 +62,8 @@ declare function buildCloudflareOutput(options?: BuildCloudflareOutputOptions):
60
62
  * every build — run `cloudflare:build` after adding a migration.
61
63
  */
62
64
  declare function flattenD1Migrations(migrationsDir: string, outDir: string): void;
63
-
65
+ //#endregion
66
+ //#region src/storage/R2Driver.d.ts
64
67
  /**
65
68
  * Structural view of the R2 binding, in the same spirit as the S3 driver's
66
69
  * local `S3Client { send() }`: only what this driver calls, so
@@ -68,19 +71,19 @@ declare function flattenD1Migrations(migrationsDir: string, outDir: string): voi
68
71
  * pins that the real `R2Bucket` satisfies it.
69
72
  */
70
73
  interface R2HttpMetadataLike {
71
- contentType?: string;
72
- contentLanguage?: string;
73
- contentDisposition?: string;
74
- contentEncoding?: string;
75
- cacheControl?: string;
76
- cacheExpiry?: Date;
74
+ contentType?: string;
75
+ contentLanguage?: string;
76
+ contentDisposition?: string;
77
+ contentEncoding?: string;
78
+ cacheControl?: string;
79
+ cacheExpiry?: Date;
77
80
  }
78
81
  interface R2ObjectLike {
79
- key: string;
80
- size: number;
81
- uploaded: Date;
82
- httpMetadata?: R2HttpMetadataLike;
83
- customMetadata?: Record<string, string>;
82
+ key: string;
83
+ size: number;
84
+ uploaded: Date;
85
+ httpMetadata?: R2HttpMetadataLike;
86
+ customMetadata?: Record<string, string>;
84
87
  }
85
88
  /**
86
89
  * Streams and blobs are typed structurally rather than as the global
@@ -90,85 +93,85 @@ interface R2ObjectLike {
90
93
  * the `R2BucketLike` check while being perfectly usable at runtime.
91
94
  */
92
95
  interface R2StreamLike {
93
- locked: boolean;
94
- getReader(): unknown;
95
- cancel(reason?: unknown): Promise<void>;
96
+ locked: boolean;
97
+ getReader(): unknown;
98
+ cancel(reason?: unknown): Promise<void>;
96
99
  }
97
100
  interface R2BlobLike {
98
- size: number;
99
- type: string;
100
- arrayBuffer(): Promise<ArrayBuffer>;
101
- text(): Promise<string>;
101
+ size: number;
102
+ type: string;
103
+ arrayBuffer(): Promise<ArrayBuffer>;
104
+ text(): Promise<string>;
102
105
  }
103
106
  interface R2ObjectBodyLike extends R2ObjectLike {
104
- body: R2StreamLike;
105
- arrayBuffer(): Promise<ArrayBuffer>;
106
- text(): Promise<string>;
107
+ body: R2StreamLike;
108
+ arrayBuffer(): Promise<ArrayBuffer>;
109
+ text(): Promise<string>;
107
110
  }
108
111
  interface R2ObjectsLike {
109
- objects: R2ObjectLike[];
110
- truncated: boolean;
111
- cursor?: string;
112
- delimitedPrefixes: string[];
112
+ objects: R2ObjectLike[];
113
+ truncated: boolean;
114
+ cursor?: string;
115
+ delimitedPrefixes: string[];
113
116
  }
114
117
  interface R2ListOptionsLike {
115
- prefix?: string;
116
- delimiter?: string;
117
- cursor?: string;
118
- limit?: number;
118
+ prefix?: string;
119
+ delimiter?: string;
120
+ cursor?: string;
121
+ limit?: number;
119
122
  }
120
123
  interface R2PutOptionsLike {
121
- httpMetadata?: R2HttpMetadataLike;
122
- customMetadata?: Record<string, string>;
124
+ httpMetadata?: R2HttpMetadataLike;
125
+ customMetadata?: Record<string, string>;
123
126
  }
124
127
  type R2PutValue = R2StreamLike | R2BlobLike | ArrayBuffer | ArrayBufferView | string | null;
125
128
  interface R2BucketLike {
126
- head(key: string): Promise<R2ObjectLike | null>;
127
- get(key: string): Promise<R2ObjectBodyLike | null>;
128
- put(key: string, value: R2PutValue, options?: R2PutOptionsLike): Promise<R2ObjectLike | null>;
129
- delete(keys: string | string[]): Promise<void>;
130
- list(options?: R2ListOptionsLike): Promise<R2ObjectsLike>;
129
+ head(key: string): Promise<R2ObjectLike | null>;
130
+ get(key: string): Promise<R2ObjectBodyLike | null>;
131
+ put(key: string, value: R2PutValue, options?: R2PutOptionsLike): Promise<R2ObjectLike | null>;
132
+ delete(keys: string | string[]): Promise<void>;
133
+ list(options?: R2ListOptionsLike): Promise<R2ObjectsLike>;
131
134
  }
132
135
  interface R2PresignOptions {
133
- /** Cloudflare account id — the S3 endpoint is `https://<accountId>.r2.cloudflarestorage.com`. */
134
- accountId: string;
135
- /** Bucket name as R2 knows it (the binding does not expose it). */
136
- bucket: string;
137
- /** R2 API token credentials (S3-compatible access key pair). */
138
- accessKeyId: string;
139
- secretAccessKey: string;
136
+ /** Cloudflare account id — the S3 endpoint is `https://<accountId>.r2.cloudflarestorage.com`. */
137
+ accountId: string;
138
+ /** Bucket name as R2 knows it (the binding does not expose it). */
139
+ bucket: string;
140
+ /** R2 API token credentials (S3-compatible access key pair). */
141
+ accessKeyId: string;
142
+ secretAccessKey: string;
140
143
  }
141
144
  interface R2DriverOptions {
142
- /**
143
- * Resolver returning the R2 bucket binding. Bindings arrive with the first
144
- * request on Workers, so this must be a deferred closure, e.g.
145
- * `binding: () => getWorkersEnv<Env>().BUCKET` — the same contract as
146
- * `createD1Database({ binding })`.
147
- */
148
- binding: () => unknown;
149
- /**
150
- * Base URL for `url()`: the bucket's custom domain (recommended) or its
151
- * r2.dev subdomain. R2 has no derivable default — unlike S3 there is no
152
- * `https://<bucket>.s3.<region>.amazonaws.com` — so `url()` throws with
153
- * guidance when this is unset.
154
- */
155
- publicUrl?: string;
156
- /** Key prefix, same semantics as `S3DriverOptions.prefix`. */
157
- prefix?: string;
158
- /**
159
- * The visibility every object in this bucket effectively has. R2 has no
160
- * per-object ACL: a bucket is public (custom domain / r2.dev) or it is not.
161
- * Defaults to `'public'` when `publicUrl` is set, `'private'` otherwise.
162
- * `put({ visibility })` and `setVisibility()` throw when asked for the
163
- * other value — the driver refuses to pretend it can enforce a per-object
164
- * flag it cannot.
165
- */
166
- visibility?: 'public' | 'private';
167
- /**
168
- * S3 API credentials used only by `temporaryUrl()`. Optional — omit it and
169
- * `temporaryUrl()` throws with guidance.
170
- */
171
- presign?: R2PresignOptions;
145
+ /**
146
+ * Resolver returning the R2 bucket binding. Bindings arrive with the first
147
+ * request on Workers, so this must be a deferred closure, e.g.
148
+ * `binding: () => getWorkersEnv<Env>().BUCKET` — the same contract as
149
+ * `createD1Database({ binding })`.
150
+ */
151
+ binding: () => unknown;
152
+ /**
153
+ * Base URL for `url()`: the bucket's custom domain (recommended) or its
154
+ * r2.dev subdomain. R2 has no derivable default — unlike S3 there is no
155
+ * `https://<bucket>.s3.<region>.amazonaws.com` — so `url()` throws with
156
+ * guidance when this is unset.
157
+ */
158
+ publicUrl?: string;
159
+ /** Key prefix, same semantics as `S3DriverOptions.prefix`. */
160
+ prefix?: string;
161
+ /**
162
+ * The visibility every object in this bucket effectively has. R2 has no
163
+ * per-object ACL: a bucket is public (custom domain / r2.dev) or it is not.
164
+ * Defaults to `'public'` when `publicUrl` is set, `'private'` otherwise.
165
+ * `put({ visibility })` and `setVisibility()` throw when asked for the
166
+ * other value — the driver refuses to pretend it can enforce a per-object
167
+ * flag it cannot.
168
+ */
169
+ visibility?: 'public' | 'private';
170
+ /**
171
+ * S3 API credentials used only by `temporaryUrl()`. Optional — omit it and
172
+ * `temporaryUrl()` throws with guidance.
173
+ */
174
+ presign?: R2PresignOptions;
172
175
  }
173
176
  /**
174
177
  * Cloudflare R2 storage driver over the Workers binding.
@@ -183,60 +186,60 @@ interface R2DriverOptions {
183
186
  * ```
184
187
  */
185
188
  declare class R2Driver implements StorageDriver {
186
- private readonly resolveBinding;
187
- private readonly publicUrl?;
188
- private readonly prefix;
189
- private readonly diskVisibility;
190
- private readonly presign?;
191
- constructor(options: R2DriverOptions);
192
- private bucket;
193
- private key;
194
- /** Inverse of `key()`: strips the prefix so listings return app-relative paths. */
195
- private unkey;
196
- private directoryPrefix;
197
- private assertVisibility;
198
- put(path: string, content: Buffer | string, options?: PutOptions): Promise<string>;
199
- putFile(_path: string, _localPath: string, _options?: PutOptions): Promise<string>;
200
- get(path: string): Promise<Buffer | null>;
201
- getAsString(path: string): Promise<string | null>;
202
- exists(path: string): Promise<boolean>;
203
- delete(path: string): Promise<boolean>;
204
- deleteMany(paths: string[]): Promise<number>;
205
- private deleteKeys;
206
- copy(from: string, to: string): Promise<string>;
207
- move(from: string, to: string): Promise<string>;
208
- url(path: string): string;
209
- temporaryUrl(path: string, expiration: Date): Promise<string>;
210
- size(path: string): Promise<number>;
211
- lastModified(path: string): Promise<Date>;
212
- private metadataOrFail;
213
- metadata(path: string): Promise<FileMetadata | null>;
214
- files(directory: string): Promise<string[]>;
215
- directories(directory: string): Promise<string[]>;
216
- allFiles(directory: string): Promise<string[]>;
217
- /** App-relative paths of every listed object, minus folder markers. */
218
- private collectFiles;
219
- private objects;
220
- /**
221
- * Follows `cursor` until `truncated` is false. A single `list()` call is
222
- * capped at 1000 keys, so a one-page read (what `S3Driver.allFiles` does)
223
- * silently truncates larger directories.
224
- */
225
- private pages;
226
- makeDirectory(path: string): Promise<void>;
227
- deleteDirectory(path: string): Promise<void>;
228
- setVisibility(path: string, visibility: 'public' | 'private'): Promise<void>;
229
- getVisibility(path: string): Promise<'public' | 'private'>;
230
- /** The key prefix (for tests and diagnostics). */
231
- getPrefix(): string;
232
- }
233
-
189
+ private readonly resolveBinding;
190
+ private readonly publicUrl?;
191
+ private readonly prefix;
192
+ private readonly diskVisibility;
193
+ private readonly presign?;
194
+ constructor(options: R2DriverOptions);
195
+ private bucket;
196
+ private key;
197
+ /** Inverse of `key()`: strips the prefix so listings return app-relative paths. */
198
+ private unkey;
199
+ private directoryPrefix;
200
+ private assertVisibility;
201
+ put(path: string, content: Buffer | string, options?: PutOptions): Promise<string>;
202
+ putFile(_path: string, _localPath: string, _options?: PutOptions): Promise<string>;
203
+ get(path: string): Promise<Buffer | null>;
204
+ getAsString(path: string): Promise<string | null>;
205
+ exists(path: string): Promise<boolean>;
206
+ delete(path: string): Promise<boolean>;
207
+ deleteMany(paths: string[]): Promise<number>;
208
+ private deleteKeys;
209
+ copy(from: string, to: string): Promise<string>;
210
+ move(from: string, to: string): Promise<string>;
211
+ url(path: string): string;
212
+ temporaryUrl(path: string, expiration: Date): Promise<string>;
213
+ size(path: string): Promise<number>;
214
+ lastModified(path: string): Promise<Date>;
215
+ private metadataOrFail;
216
+ metadata(path: string): Promise<FileMetadata | null>;
217
+ files(directory: string): Promise<string[]>;
218
+ directories(directory: string): Promise<string[]>;
219
+ allFiles(directory: string): Promise<string[]>;
220
+ /** App-relative paths of every listed object, minus folder markers. */
221
+ private collectFiles;
222
+ private objects;
223
+ /**
224
+ * Follows `cursor` until `truncated` is false. A single `list()` call is
225
+ * capped at 1000 keys, so a one-page read silently truncates larger
226
+ * directories.
227
+ */
228
+ private pages;
229
+ makeDirectory(path: string): Promise<void>;
230
+ deleteDirectory(path: string): Promise<void>;
231
+ setVisibility(path: string, visibility: 'public' | 'private'): Promise<void>;
232
+ getVisibility(path: string): Promise<'public' | 'private'>;
233
+ /** The key prefix (for tests and diagnostics). */
234
+ getPrefix(): string;
235
+ }
236
+ //#endregion
237
+ //#region src/index.d.ts
234
238
  /**
235
239
  * Configuration for the Cloudflare plugin. Currently empty — reserved for
236
240
  * upcoming RFC 0003 parts (session/OAuth-state store wiring on Workers).
237
241
  */
238
- interface CloudflarePluginConfig {
239
- }
242
+ interface CloudflarePluginConfig {}
240
243
  /**
241
244
  * Register the Cloudflare plugin.
242
245
  *
@@ -246,5 +249,5 @@ interface CloudflarePluginConfig {
246
249
  * ```
247
250
  */
248
251
  declare function cloudflarePlugin(config?: CloudflarePluginConfig): ServiceProviderConstructor;
249
-
250
- export { type BuildCloudflareOutputOptions, type CloudflarePluginConfig, type R2BucketLike, R2Driver, type R2DriverOptions, type R2PresignOptions, type WorkersAppLike, type WorkersExecutionContext, type WorkersHandler, buildCloudflareOutput, captureWorkersEnv, cloudflarePlugin, createWorkersHandler, flattenD1Migrations, getWorkersEnv, resetWorkersEnv };
252
+ //#endregion
253
+ export { type BuildCloudflareOutputOptions, CloudflarePluginConfig, type R2BucketLike, R2Driver, type R2DriverOptions, type R2PresignOptions, type WorkersAppLike, type WorkersExecutionContext, type WorkersHandler, buildCloudflareOutput, captureWorkersEnv, cloudflarePlugin, createWorkersHandler, flattenD1Migrations, getWorkersEnv, resetWorkersEnv };