effect-cf 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # effect-cf
 
+## 0.9.1
+
+### Patch Changes
+
+- [#27](https://github.com/danieljvdm/effect-cf/pull/27) [`ac2fb0f`](https://github.com/danieljvdm/effect-cf/commit/ac2fb0f9b557c1f73d779ed024c03245c1850b02) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Wrap R2 object body reader methods in Effect so `json`, `text`, `bytes`, `arrayBuffer`, and `blob` report read failures as `R2OperationError`.
+
+## 0.9.0
+
+### Minor Changes
+
+- [#25](https://github.com/danieljvdm/effect-cf/pull/25) [`c7daaff`](https://github.com/danieljvdm/effect-cf/commit/c7daaff779934c83519ad9689e1f98dc100b5251) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add a Durable Object `initialize` hook for running Effect setup each time Cloudflare loads a Durable Object instance into memory.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -240,6 +240,25 @@ In definition-backed workflows, the `payload` argument is the typed decoded payl
 
 ## Durable Object WebSockets
 
+Use `initialize` for work that should run each time Cloudflare loads a Durable
+Object instance into memory. Yield `state.blockConcurrencyWhile(...)` when
+later events should wait for initialize to finish. If work should happen only once
+for a Durable Object id, store a sentinel in Durable Object storage.
+
+```ts
+export const RoomLive = DurableObject.make(layer, {
+  initialize: Effect.gen(function* () {
+    const state = yield* DurableObjectState.DurableObjectState;
+    yield* state.blockConcurrencyWhile(
+      Effect.gen(function* () {
+        yield* state.storage.put("loadedAt", Date.now());
+      }),
+    );
+  }),
+  fetch,
+});
+```
+
 Durable Object application sockets should use the hibernation-compatible state API. Accept sockets with `DurableObjectWebSocket.acceptUpgrade(...)`; do not call `server.accept()` or attach native `message` listeners in application code.
 
 ```ts

package/dist/index.d.mts

@@ -376,7 +376,7 @@ declare const method$3: {
   <Success extends ServiceFreeSchema$3>(definition: {
     readonly success: Success;
   }): Method$4<readonly [], Success>;
-  <const Args extends ReadonlyArray<ServiceFreeSchema$3>, Success extends ServiceFreeSchema$3>(definition: {
+  <const Args extends readonly ServiceFreeSchema$3[], Success extends ServiceFreeSchema$3>(definition: {
     readonly args: Args;
     readonly success: Success;
   }): Method$4<Args, Success>;
@@ -1288,6 +1288,15 @@ type RpcHandlers<ROut, Api> = { readonly [Key in keyof Api as Key extends keyof
  * Options for creating a Durable Object class backed by Effect handlers.
  */
 interface DurableObjectOptions<ROut, Rpc extends DurableObjectRpc<ROut>> {
+  /**
+   * Effect run when Cloudflare loads this Durable Object instance into memory.
+   *
+   * Use `DurableObjectState.blockConcurrencyWhile` inside this hook when
+   * incoming events should wait for setup to finish. Cloudflare may construct
+   * the same Durable Object id again after eviction or restart; use Durable
+   * Object storage if work must happen only once per id.
+   */
+  readonly initialize?: Effect.Effect<void, unknown, HandlerContext<ROut>>;
   /** Optional RPC methods exposed as Durable Object instance methods. */
   readonly rpc?: Rpc;
   /** Optional fetch handler for HTTP/WebSocket requests. */
@@ -1912,7 +1921,7 @@ declare const Tag$4: <Self>() => <Id extends string, Key, Value, EncodedValue>(i
   readonly value: Schema.Codec<Value, EncodedValue>;
 }) => TagClass$3<Self, Id, Key, Value, EncodedValue>;
 declare namespace R2_d_exports {
-  export { LayerOptions$2 as LayerOptions, R2Client, R2Definition, R2GetOptions, R2ListOptions, R2MultipartOptions, R2MultipartUploadClient, R2OperationError, R2PutOptions, R2PutValue, R2Service, R2UploadPartOptions, R2UploadPartValue, Tag$3 as Tag, TagClass$2 as TagClass, isR2Bucket, layer$1 as layer, make$2 as make, makeClient$1 as makeClient };
+  export { LayerOptions$2 as LayerOptions, R2Client, R2Definition, R2GetOptions, R2ListOptions, R2MultipartOptions, R2MultipartUploadClient, R2ObjectBodyClient, R2OperationError, R2PutOptions, R2PutValue, R2Service, R2UploadPartOptions, R2UploadPartValue, Tag$3 as Tag, TagClass$2 as TagClass, isR2Bucket, layer$1 as layer, make$2 as make, makeClient$1 as makeClient };
 }
 declare const R2OperationError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
   readonly _tag: "R2OperationError";
@@ -1935,6 +1944,14 @@ type R2MultipartOptions = globalThis.R2MultipartOptions;
 type R2UploadPartOptions = globalThis.R2UploadPartOptions;
 type R2PutValue = ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob;
 type R2UploadPartValue = ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob;
+interface R2ObjectBodyClient extends Omit<globalThis.R2ObjectBody, "arrayBuffer" | "blob" | "bytes" | "json" | "text"> {
+  readonly raw: globalThis.R2ObjectBody;
+  readonly arrayBuffer: Effect.Effect<ArrayBuffer, R2OperationError>;
+  readonly bytes: Effect.Effect<Uint8Array, R2OperationError>;
+  readonly text: Effect.Effect<string, R2OperationError>;
+  readonly json: <T = unknown>() => Effect.Effect<T, R2OperationError>;
+  readonly blob: Effect.Effect<Blob, R2OperationError>;
+}
 interface R2MultipartUploadClient {
   readonly raw: globalThis.R2MultipartUpload;
   readonly key: string;
@@ -1948,8 +1965,8 @@ interface R2Client {
   readonly get: {
     (key: string, options: R2GetOptions & {
       readonly onlyIf: globalThis.R2Conditional | Headers;
-    }): Effect.Effect<Option.Option<globalThis.R2ObjectBody | globalThis.R2Object>, R2OperationError>;
-    (key: string, options?: R2GetOptions): Effect.Effect<Option.Option<globalThis.R2ObjectBody>, R2OperationError>;
+    }): Effect.Effect<Option.Option<R2ObjectBodyClient | globalThis.R2Object>, R2OperationError>;
+    (key: string, options?: R2GetOptions): Effect.Effect<Option.Option<R2ObjectBodyClient>, R2OperationError>;
   };
   readonly put: {
     (key: string, value: R2PutValue, options: R2PutOptions & {

package/dist/index.mjs

@@ -1253,6 +1253,8 @@ const make$4 = (layer, options = {}) => {
 			super(state, env);
 			const runtimeLayer = provideEntrypointServices(layer, Layer.mergeAll(Layer.succeed(DurableObjectState, fromDurableObjectState(state)), Layer.succeed(WorkerEnvironment, env)));
 			this.runtime = ManagedRuntime.make(runtimeLayer);
+			const initialize = options.initialize;
+			if (initialize !== void 0) state.waitUntil(this[RunSymbol](initialize));
 		}
 		[RunSymbol](effect) {
 			return this.runtime.runPromise(Effect.scoped(effect));
@@ -1976,6 +1978,36 @@ const tryR2Sync = (binding, operation, evaluate) => Effect.try({
 	catch: (cause) => r2Error(binding, operation, cause)
 });
 const maybe = (value) => value === null ? Option.none() : Option.some(value);
+const isR2ObjectBody = (value) => "body" in value && typeof value.arrayBuffer === "function" && typeof value.bytes === "function" && typeof value.text === "function" && typeof value.json === "function" && typeof value.blob === "function";
+const wrapObjectBody = (binding, object) => ({
+	key: object.key,
+	version: object.version,
+	size: object.size,
+	etag: object.etag,
+	httpEtag: object.httpEtag,
+	checksums: object.checksums,
+	uploaded: object.uploaded,
+	httpMetadata: object.httpMetadata,
+	customMetadata: object.customMetadata,
+	range: object.range,
+	storageClass: object.storageClass,
+	ssecKeyMd5: object.ssecKeyMd5,
+	writeHttpMetadata: (headers) => object.writeHttpMetadata(headers),
+	raw: object,
+	body: object.body,
+	get bodyUsed() {
+		return object.bodyUsed;
+	},
+	arrayBuffer: tryR2Promise(binding, "arrayBuffer", () => object.arrayBuffer()),
+	bytes: tryR2Promise(binding, "bytes", () => object.bytes()),
+	text: tryR2Promise(binding, "text", () => object.text()),
+	json: () => tryR2Promise(binding, "json", () => object.json()),
+	blob: tryR2Promise(binding, "blob", () => object.blob())
+});
+const wrapGetResult = (binding, object) => {
+	if (object === null || !isR2ObjectBody(object)) return object;
+	return wrapObjectBody(binding, object);
+};
 const isR2Bucket = (value) => {
 	if (typeof value !== "object" || value === null) return false;
 	const resource = value;
@@ -1990,24 +2022,27 @@ const makeClient$1 = (definition) => {
 		abort: tryR2Promise(definition.binding, "abortMultipartUpload", () => upload.abort()),
 		complete: (uploadedParts) => tryR2Promise(definition.binding, "completeMultipartUpload", () => upload.complete([...uploadedParts]))
 	});
-	return (bucket) => ({
-		definition,
-		head: (key) => tryR2Promise(definition.binding, "head", () => bucket.head(key)).pipe(Effect.map(maybe)),
-		get: ((key, options) => tryR2Promise(definition.binding, "get", () => bucket.get(key, options)).pipe(Effect.map(maybe))),
-		put: ((key, value, options) => tryR2Promise(definition.binding, "put", () => bucket.put(key, value, options)).pipe(Effect.map((object) => {
-			if (object === null) return Option.none();
-			if (options !== void 0 && "onlyIf" in options) return Option.some(object);
-			return object;
-		}))),
-		createMultipartUpload: (key, options) => tryR2Promise(definition.binding, "createMultipartUpload", () => bucket.createMultipartUpload(key, options)).pipe(Effect.map(wrapUpload)),
-		resumeMultipartUpload: (key, uploadId) => tryR2Sync(definition.binding, "resumeMultipartUpload", () => wrapUpload(bucket.resumeMultipartUpload(key, uploadId))),
-		delete: (keys) => {
-			const nativeKeys = typeof keys === "string" ? keys : [...keys];
-			return tryR2Promise(definition.binding, "delete", () => bucket.delete(nativeKeys));
-		},
-		list: (options) => tryR2Promise(definition.binding, "list", () => bucket.list(options)),
-		unsafeRaw: Effect.succeed(bucket)
-	});
+	return (bucket) => {
+		const get = ((key, options) => tryR2Promise(definition.binding, "get", () => bucket.get(key, options)).pipe(Effect.map((object) => maybe(wrapGetResult(definition.binding, object)))));
+		return {
+			definition,
+			head: (key) => tryR2Promise(definition.binding, "head", () => bucket.head(key)).pipe(Effect.map(maybe)),
+			get,
+			put: ((key, value, options) => tryR2Promise(definition.binding, "put", () => bucket.put(key, value, options)).pipe(Effect.map((object) => {
+				if (object === null) return Option.none();
+				if (options !== void 0 && "onlyIf" in options) return Option.some(object);
+				return object;
+			}))),
+			createMultipartUpload: (key, options) => tryR2Promise(definition.binding, "createMultipartUpload", () => bucket.createMultipartUpload(key, options)).pipe(Effect.map(wrapUpload)),
+			resumeMultipartUpload: (key, uploadId) => tryR2Sync(definition.binding, "resumeMultipartUpload", () => wrapUpload(bucket.resumeMultipartUpload(key, uploadId))),
+			delete: (keys) => {
+				const nativeKeys = typeof keys === "string" ? keys : [...keys];
+				return tryR2Promise(definition.binding, "delete", () => bucket.delete(nativeKeys));
+			},
+			list: (options) => tryR2Promise(definition.binding, "list", () => bucket.list(options)),
+			unsafeRaw: Effect.succeed(bucket)
+		};
+	};
 };
 const layer$1 = (tag, definition) => layer$8(tag, definition.binding, isR2Bucket, makeClient$1(definition));
 const make$2 = (id) => Tag$2()(id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {

package/src/DurableObject.ts

@@ -73,6 +73,15 @@ export type RpcHandlers<ROut, Api> = {
  * Options for creating a Durable Object class backed by Effect handlers.
  */
 export interface DurableObjectOptions<ROut, Rpc extends DurableObjectRpc<ROut>> {
+  /**
+   * Effect run when Cloudflare loads this Durable Object instance into memory.
+   *
+   * Use `DurableObjectState.blockConcurrencyWhile` inside this hook when
+   * incoming events should wait for setup to finish. Cloudflare may construct
+   * the same Durable Object id again after eviction or restart; use Durable
+   * Object storage if work must happen only once per id.
+   */
+  readonly initialize?: Effect.Effect<void, unknown, HandlerContext<ROut>>;
   /** Optional RPC methods exposed as Durable Object instance methods. */
   readonly rpc?: Rpc;
   /** Optional fetch handler for HTTP/WebSocket requests. */
@@ -137,6 +146,11 @@ export const make = <
       const runtimeLayer = Entrypoint.provideEntrypointServices(layer, services);
 
       this.runtime = ManagedRuntime.make(runtimeLayer);
+
+      const initialize = options.initialize;
+      if (initialize !== undefined) {
+        state.waitUntil(this[RunSymbol](initialize));
+      }
     }
 
     [RunSymbol]<A, E>(effect: Effect.Effect<A, E, HandlerContext<ROut>>): Promise<A> {

package/src/R2.ts

@@ -24,6 +24,18 @@ export type R2UploadPartOptions = globalThis.R2UploadPartOptions;
 export type R2PutValue = ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob;
 export type R2UploadPartValue = ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob;
 
+export interface R2ObjectBodyClient extends Omit<
+  globalThis.R2ObjectBody,
+  "arrayBuffer" | "blob" | "bytes" | "json" | "text"
+> {
+  readonly raw: globalThis.R2ObjectBody;
+  readonly arrayBuffer: Effect.Effect<ArrayBuffer, R2OperationError>;
+  readonly bytes: Effect.Effect<Uint8Array, R2OperationError>;
+  readonly text: Effect.Effect<string, R2OperationError>;
+  readonly json: <T = unknown>() => Effect.Effect<T, R2OperationError>;
+  readonly blob: Effect.Effect<Blob, R2OperationError>;
+}
+
 export interface R2MultipartUploadClient {
   readonly raw: globalThis.R2MultipartUpload;
   readonly key: string;
@@ -47,14 +59,11 @@ export interface R2Client {
     (
       key: string,
       options: R2GetOptions & { readonly onlyIf: globalThis.R2Conditional | Headers },
-    ): Effect.Effect<
-      Option.Option<globalThis.R2ObjectBody | globalThis.R2Object>,
-      R2OperationError
-    >;
+    ): Effect.Effect<Option.Option<R2ObjectBodyClient | globalThis.R2Object>, R2OperationError>;
     (
       key: string,
       options?: R2GetOptions,
-    ): Effect.Effect<Option.Option<globalThis.R2ObjectBody>, R2OperationError>;
+    ): Effect.Effect<Option.Option<R2ObjectBodyClient>, R2OperationError>;
   };
   readonly put: {
     (
@@ -136,6 +145,53 @@ const tryR2Sync = <A>(
 const maybe = <A>(value: A | null): Option.Option<A> =>
   value === null ? Option.none() : Option.some(value);
 
+const isR2ObjectBody = (
+  value: globalThis.R2ObjectBody | globalThis.R2Object,
+): value is globalThis.R2ObjectBody =>
+  "body" in value &&
+  typeof (value as globalThis.R2ObjectBody).arrayBuffer === "function" &&
+  typeof (value as globalThis.R2ObjectBody).bytes === "function" &&
+  typeof (value as globalThis.R2ObjectBody).text === "function" &&
+  typeof (value as globalThis.R2ObjectBody).json === "function" &&
+  typeof (value as globalThis.R2ObjectBody).blob === "function";
+
+const wrapObjectBody = (binding: string, object: globalThis.R2ObjectBody): R2ObjectBodyClient => ({
+  key: object.key,
+  version: object.version,
+  size: object.size,
+  etag: object.etag,
+  httpEtag: object.httpEtag,
+  checksums: object.checksums,
+  uploaded: object.uploaded,
+  httpMetadata: object.httpMetadata,
+  customMetadata: object.customMetadata,
+  range: object.range,
+  storageClass: object.storageClass,
+  ssecKeyMd5: object.ssecKeyMd5,
+  writeHttpMetadata: (headers) => object.writeHttpMetadata(headers),
+  raw: object,
+  body: object.body,
+  get bodyUsed() {
+    return object.bodyUsed;
+  },
+  arrayBuffer: tryR2Promise(binding, "arrayBuffer", () => object.arrayBuffer()),
+  bytes: tryR2Promise(binding, "bytes", () => object.bytes()),
+  text: tryR2Promise(binding, "text", () => object.text()),
+  json: <T = unknown>() => tryR2Promise(binding, "json", () => object.json<T>()),
+  blob: tryR2Promise(binding, "blob", () => object.blob()),
+});
+
+const wrapGetResult = (
+  binding: string,
+  object: globalThis.R2ObjectBody | globalThis.R2Object | null,
+): R2ObjectBodyClient | globalThis.R2Object | null => {
+  if (object === null || !isR2ObjectBody(object)) {
+    return object;
+  }
+
+  return wrapObjectBody(binding, object);
+};
+
 export const isR2Bucket = (value: unknown): value is globalThis.R2Bucket => {
   if (typeof value !== "object" || value === null) {
     return false;
@@ -172,43 +228,47 @@ export const makeClient = (
       ),
   });
 
-  return (bucket) => ({
-    definition,
-    head: (key) =>
-      tryR2Promise(definition.binding, "head", () => bucket.head(key)).pipe(Effect.map(maybe)),
-    get: ((key: string, options?: R2GetOptions) =>
+  return (bucket) => {
+    const get = ((key: string, options?: R2GetOptions) =>
       tryR2Promise(definition.binding, "get", () => bucket.get(key, options)).pipe(
-        Effect.map(maybe),
-      )) as R2Client["get"],
-    put: ((key: string, value: R2PutValue, options?: R2PutOptions) =>
-      tryR2Promise(definition.binding, "put", () => bucket.put(key, value, options)).pipe(
-        Effect.map((object) => {
-          if (object === null) {
-            return Option.none<globalThis.R2Object>();
-          }
-
-          if (options !== undefined && "onlyIf" in options) {
-            return Option.some(object);
-          }
-
-          return object;
-        }),
-      )) as R2Client["put"],
-    createMultipartUpload: (key, options) =>
-      tryR2Promise(definition.binding, "createMultipartUpload", () =>
-        bucket.createMultipartUpload(key, options),
-      ).pipe(Effect.map(wrapUpload)),
-    resumeMultipartUpload: (key, uploadId) =>
-      tryR2Sync(definition.binding, "resumeMultipartUpload", () =>
-        wrapUpload(bucket.resumeMultipartUpload(key, uploadId)),
-      ),
-    delete: (keys) => {
-      const nativeKeys = typeof keys === "string" ? keys : [...keys];
-      return tryR2Promise(definition.binding, "delete", () => bucket.delete(nativeKeys));
-    },
-    list: (options) => tryR2Promise(definition.binding, "list", () => bucket.list(options)),
-    unsafeRaw: Effect.succeed(bucket),
-  });
+        Effect.map((object) => maybe(wrapGetResult(definition.binding, object))),
+      )) as R2Client["get"];
+
+    return {
+      definition,
+      head: (key) =>
+        tryR2Promise(definition.binding, "head", () => bucket.head(key)).pipe(Effect.map(maybe)),
+      get,
+      put: ((key: string, value: R2PutValue, options?: R2PutOptions) =>
+        tryR2Promise(definition.binding, "put", () => bucket.put(key, value, options)).pipe(
+          Effect.map((object) => {
+            if (object === null) {
+              return Option.none<globalThis.R2Object>();
+            }
+
+            if (options !== undefined && "onlyIf" in options) {
+              return Option.some(object);
+            }
+
+            return object;
+          }),
+        )) as R2Client["put"],
+      createMultipartUpload: (key, options) =>
+        tryR2Promise(definition.binding, "createMultipartUpload", () =>
+          bucket.createMultipartUpload(key, options),
+        ).pipe(Effect.map(wrapUpload)),
+      resumeMultipartUpload: (key, uploadId) =>
+        tryR2Sync(definition.binding, "resumeMultipartUpload", () =>
+          wrapUpload(bucket.resumeMultipartUpload(key, uploadId)),
+        ),
+      delete: (keys) => {
+        const nativeKeys = typeof keys === "string" ? keys : [...keys];
+        return tryR2Promise(definition.binding, "delete", () => bucket.delete(nativeKeys));
+      },
+      list: (options) => tryR2Promise(definition.binding, "list", () => bucket.list(options)),
+      unsafeRaw: Effect.succeed(bucket),
+    };
+  };
 };
 
 export const layer = <Self>(tag: Context.Service<Self, R2Client>, definition: R2Definition) =>