durable-cf-streams 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# durable-cf-streams
+
+building blocks for [durable streams](https://github.com/durable-streams) on cloudflare. storage backends and utilities. the idea is that you can borrow utilities and wire up http (or whatever) however you want.
+
+## install
+
+```bash
+pnpm add durable-cf-streams
+```
+
+## storage backends
+
+```typescript
+import { MemoryStore } from "durable-cf-streams/storage/memory";
+import { D1Store } from "durable-cf-streams/storage/d1";
+import { KVStore } from "durable-cf-streams/storage/kv";
+import { R2Store } from "durable-cf-streams/storage/r2";
+
+// in-memory (for durable objects)
+const store = new MemoryStore();
+
+// d1 database
+const store = new D1Store(env.DB);
+await store.initialize(); // creates table
+
+// workers kv
+const store = new KVStore(env.KV);
+
+// r2 bucket
+const store = new R2Store(env.BUCKET);
+```
+
+## streamstore interface
+
+```typescript
+interface StreamStore {
+  put(path: string, options: PutOptions): Promise<PutResult>;
+  append(path: string, data: Uint8Array, options?: AppendOptions): Promise<AppendResult>;
+  get(path: string, options?: GetOptions): Promise<GetResult>;
+  head(path: string): Promise<HeadResult | null>;
+  delete(path: string): Promise<void>;
+  has(path: string): boolean;
+  waitForData(path: string, offset: string, timeoutMs: number): Promise<WaitResult>;
+  formatResponse(path: string, messages: StreamMessage[]): Uint8Array;
+}
+```
+
+## utilities
+
+```typescript
+import {
+  // offsets
+  parseOffset,
+  formatOffset,
+  compareOffsets,
+  isValidOffset,
+  initialOffset,
+  
+  // cursors
+  generateCursor,
+  getNextCursor,
+  
+  // protocol
+  normalizeContentType,
+  validateTTL,
+  validateExpiresAt,
+  generateETag,
+  isJsonContentType,
+} from "durable-cf-streams";
+```
+
+## errors
+
+tagged errors for pattern matching:
+
+```typescript
+import {
+  StreamNotFoundError,
+  SequenceConflictError,
+  ContentTypeMismatchError,
+  StreamConflictError,
+  InvalidJsonError,
+  PayloadTooLargeError,
+} from "durable-cf-streams";
+
+// check error type
+if (error instanceof StreamNotFoundError) {
+  return new Response("not found", { status: 404 });
+}
+
+// or use _tag for switch
+switch (error._tag) {
+  case "StreamNotFoundError": return new Response("not found", { status: 404 });
+  case "SequenceConflictError": return new Response("conflict", { status: 409 });
+}
+```
+
+## example
+
+```typescript
+import { MemoryStore } from "durable-cf-streams/storage/memory";
+import { normalizeContentType } from "durable-cf-streams";
+
+export class StreamDO implements DurableObject {
+  private store = new MemoryStore();
+
+  async fetch(request: Request): Promise<Response> {
+    const path = new URL(request.url).pathname;
+
+    if (request.method === "PUT") {
+      const contentType = request.headers.get("content-type") ?? "application/octet-stream";
+      const body = new Uint8Array(await request.arrayBuffer());
+      
+      const result = await this.store.put(path, {
+        contentType: normalizeContentType(contentType),
+        data: body.length > 0 ? body : undefined,
+      });
+
+      return new Response(null, {
+        status: result.created ? 201 : 200,
+        headers: { "Stream-Next-Offset": result.nextOffset },
+      });
+    }
+
+    // ... handle other methods
+  }
+}
+```
+
+see [examples](../../examples) for complete implementations.
+
+## license
+
+mit

package/dist/chunk-5N2UNHIW.js

@@ -0,0 +1,306 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/cursor.ts
+var CURSOR_INTERVAL_MS = 2e4;
+var generateCursor = () => {
+  const interval = Math.floor(Date.now() / CURSOR_INTERVAL_MS);
+  return interval.toString(10);
+};
+var parseCursor = (cursor) => {
+  const parsed = Number.parseInt(cursor, 10);
+  return Number.isNaN(parsed) || parsed <= 0 ? null : parsed;
+};
+var isValidCursor = (cursor) => parseCursor(cursor) !== null;
+var compareCursors = (a, b) => {
+  const parsedA = Number.parseInt(a, 10);
+  const parsedB = Number.parseInt(b, 10);
+  return parsedA - parsedB;
+};
+var isNewerCursor = (cursor, clientCursor) => {
+  if (!clientCursor) {
+    return true;
+  }
+  return compareCursors(cursor, clientCursor) > 0;
+};
+var getNextCursor = (clientCursor) => {
+  const current = generateCursor();
+  if (!clientCursor) {
+    return current;
+  }
+  const clientInterval = Number.parseInt(clientCursor, 10);
+  const currentInterval = Number.parseInt(current, 10);
+  if (currentInterval <= clientInterval) {
+    return (clientInterval + 1).toString(10);
+  }
+  return current;
+};
+
+// src/errors.ts
+var StreamNotFoundError = class extends Error {
+  _tag = "StreamNotFoundError";
+  path;
+  constructor(path) {
+    super(`Stream not found: ${path}`);
+    this.name = "StreamNotFoundError";
+    this.path = path;
+  }
+};
+var StreamConflictError = class extends Error {
+  _tag = "StreamConflictError";
+  constructor(message) {
+    super(message);
+    this.name = "StreamConflictError";
+  }
+};
+var SequenceConflictError = class extends Error {
+  _tag = "SequenceConflictError";
+  expected;
+  received;
+  constructor(expected, received) {
+    super(`Sequence conflict: expected ${expected}, received ${received}`);
+    this.name = "SequenceConflictError";
+    this.expected = expected;
+    this.received = received;
+  }
+};
+var ContentTypeMismatchError = class extends Error {
+  _tag = "ContentTypeMismatchError";
+  expected;
+  received;
+  constructor(expected, received) {
+    super(`Content-Type mismatch: expected ${expected}, received ${received}`);
+    this.name = "ContentTypeMismatchError";
+    this.expected = expected;
+    this.received = received;
+  }
+};
+var InvalidJsonError = class extends Error {
+  _tag = "InvalidJsonError";
+  constructor(message) {
+    super(message);
+    this.name = "InvalidJsonError";
+  }
+};
+var InvalidOffsetError = class extends Error {
+  _tag = "InvalidOffsetError";
+  constructor(offset) {
+    super(`Invalid offset format: ${offset}`);
+    this.name = "InvalidOffsetError";
+  }
+};
+var PayloadTooLargeError = class extends Error {
+  _tag = "PayloadTooLargeError";
+  maxBytes;
+  receivedBytes;
+  constructor(maxBytes, receivedBytes) {
+    super(
+      `Payload too large: max ${maxBytes} bytes, received ${receivedBytes} bytes`
+    );
+    this.name = "PayloadTooLargeError";
+    this.maxBytes = maxBytes;
+    this.receivedBytes = receivedBytes;
+  }
+};
+
+// src/offsets.ts
+var OFFSET_REGEX = /^[0-9a-f]{16}_[0-9a-f]{16}$/;
+var INITIAL_OFFSET = "0000000000000000_0000000000000000";
+var SENTINEL_OFFSET = "-1";
+var initialOffset = () => INITIAL_OFFSET;
+var isSentinelOffset = (offset) => offset === SENTINEL_OFFSET;
+var isValidOffset = (offset) => offset === SENTINEL_OFFSET || OFFSET_REGEX.test(offset);
+var normalizeOffset = (offset) => offset === SENTINEL_OFFSET ? INITIAL_OFFSET : offset;
+var parseOffset = (offset) => {
+  if (!OFFSET_REGEX.test(offset)) {
+    return null;
+  }
+  const [seqHex, posHex] = offset.split("_");
+  return {
+    seq: Number.parseInt(seqHex, 16),
+    pos: Number.parseInt(posHex, 16)
+  };
+};
+var formatOffset = (seq, pos) => {
+  const seqHex = seq.toString(16).padStart(16, "0");
+  const posHex = pos.toString(16).padStart(16, "0");
+  return `${seqHex}_${posHex}`;
+};
+var compareOffsets = (a, b) => {
+  const parsedA = parseOffset(a);
+  const parsedB = parseOffset(b);
+  if (!(parsedA && parsedB)) {
+    return 0;
+  }
+  if (parsedA.seq !== parsedB.seq) {
+    return parsedA.seq < parsedB.seq ? -1 : 1;
+  }
+  if (parsedA.pos !== parsedB.pos) {
+    return parsedA.pos < parsedB.pos ? -1 : 1;
+  }
+  return 0;
+};
+var offsetToBytePos = (offset) => {
+  const parsed = parseOffset(offset);
+  return parsed ? parsed.pos : 0;
+};
+var advanceOffset = (offset, byteCount) => {
+  const parsed = parseOffset(offset);
+  if (!parsed) {
+    return offset;
+  }
+  return formatOffset(parsed.seq, parsed.pos + byteCount);
+};
+var incrementSeq = (offset) => {
+  const parsed = parseOffset(offset);
+  if (!parsed) {
+    return offset;
+  }
+  return formatOffset(parsed.seq + 1, parsed.pos);
+};
+
+// src/protocol.ts
+var TTL_REGEX = /^[1-9][0-9]*$/;
+var EXPIRES_AT_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+var ETAG_REGEX = /^"([^:]+):([^:]+):([^"]+)"$/;
+var normalizeContentType = (contentType) => {
+  const semicolonIndex = contentType.indexOf(";");
+  if (semicolonIndex !== -1) {
+    return contentType.slice(0, semicolonIndex).trim().toLowerCase();
+  }
+  return contentType.trim().toLowerCase();
+};
+var isJsonContentType = (contentType) => {
+  const normalized = normalizeContentType(contentType);
+  return normalized === "application/json" || normalized.endsWith("+json");
+};
+var validateTTL = (ttl) => {
+  if (!TTL_REGEX.test(ttl)) {
+    return null;
+  }
+  const parsed = Number.parseInt(ttl, 10);
+  return Number.isNaN(parsed) || parsed <= 0 ? null : parsed;
+};
+var validateExpiresAt = (value) => {
+  if (!EXPIRES_AT_REGEX.test(value)) {
+    return null;
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+var generateETag = (path, startOffset, endOffset) => {
+  const pathBase64 = btoa(path);
+  return `"${pathBase64}:${startOffset}:${endOffset}"`;
+};
+var parseETag = (etag) => {
+  const match = ETAG_REGEX.exec(etag);
+  if (!match || match.length < 4) {
+    return null;
+  }
+  const pathBase64 = match[1];
+  const startOffset = match[2];
+  const endOffset = match[3];
+  if (!(pathBase64 && startOffset && endOffset)) {
+    return null;
+  }
+  try {
+    return {
+      path: atob(pathBase64),
+      startOffset,
+      endOffset
+    };
+  } catch {
+    return null;
+  }
+};
+var processJsonAppend = (existing, newData) => {
+  const newStr = new TextDecoder().decode(newData).trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(newStr);
+  } catch (e) {
+    throw new InvalidJsonError(e instanceof Error ? e.message : "Invalid JSON");
+  }
+  const items = Array.isArray(parsed) ? parsed : [parsed];
+  if (items.length === 0) {
+    throw new InvalidJsonError("Empty array not allowed on append");
+  }
+  const serialized = `${items.map((item) => JSON.stringify(item)).join(",")},`;
+  const serializedBytes = new TextEncoder().encode(serialized);
+  const result = new Uint8Array(existing.length + serializedBytes.length);
+  result.set(existing);
+  result.set(serializedBytes, existing.length);
+  return result;
+};
+var formatJsonResponse = (data) => {
+  if (data.length === 0) {
+    return new TextEncoder().encode("[]");
+  }
+  let str = new TextDecoder().decode(data);
+  if (str.endsWith(",")) {
+    str = str.slice(0, -1);
+  }
+  return new TextEncoder().encode(`[${str}]`);
+};
+var validateJsonCreate = (data, isPut) => {
+  const str = new TextDecoder().decode(data).trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(str);
+  } catch (e) {
+    throw new InvalidJsonError(e instanceof Error ? e.message : "Invalid JSON");
+  }
+  let items;
+  if (Array.isArray(parsed)) {
+    if (parsed.length === 0 && !isPut) {
+      throw new InvalidJsonError("Empty array not allowed on POST");
+    }
+    items = parsed;
+  } else {
+    items = [parsed];
+  }
+  if (items.length === 0) {
+    return new Uint8Array(0);
+  }
+  const serialized = `${items.map((item) => JSON.stringify(item)).join(",")},`;
+  return new TextEncoder().encode(serialized);
+};
+
+export {
+  __export,
+  generateCursor,
+  parseCursor,
+  isValidCursor,
+  compareCursors,
+  isNewerCursor,
+  getNextCursor,
+  StreamNotFoundError,
+  StreamConflictError,
+  SequenceConflictError,
+  ContentTypeMismatchError,
+  InvalidJsonError,
+  InvalidOffsetError,
+  PayloadTooLargeError,
+  initialOffset,
+  isSentinelOffset,
+  isValidOffset,
+  normalizeOffset,
+  parseOffset,
+  formatOffset,
+  compareOffsets,
+  offsetToBytePos,
+  advanceOffset,
+  incrementSeq,
+  normalizeContentType,
+  isJsonContentType,
+  validateTTL,
+  validateExpiresAt,
+  generateETag,
+  parseETag,
+  processJsonAppend,
+  formatJsonResponse,
+  validateJsonCreate
+};

package/dist/chunk-AU5YTPHF.js

@@ -0,0 +1,239 @@
+import {
+  Deferred_exports,
+  Effect_exports
+} from "./chunk-VLDLQ6TP.js";
+import {
+  ContentTypeMismatchError,
+  SequenceConflictError,
+  StreamConflictError,
+  StreamNotFoundError,
+  formatJsonResponse,
+  formatOffset,
+  generateCursor,
+  generateETag,
+  initialOffset,
+  isJsonContentType,
+  normalizeContentType,
+  offsetToBytePos,
+  processJsonAppend,
+  validateJsonCreate
+} from "./chunk-5N2UNHIW.js";
+
+// src/storage/memory.ts
+function validateIdempotentCreate(existing, options) {
+  const existingNormalized = normalizeContentType(existing.contentType);
+  const reqNormalized = normalizeContentType(options.contentType);
+  if (existingNormalized !== reqNormalized) {
+    throw new ContentTypeMismatchError(existingNormalized, reqNormalized);
+  }
+  if (options.ttlSeconds !== existing.ttlSeconds) {
+    throw new StreamConflictError("TTL mismatch on idempotent create");
+  }
+  if (options.expiresAt !== existing.expiresAt) {
+    throw new StreamConflictError("Expires-At mismatch on idempotent create");
+  }
+}
+function prepareInitialData(options) {
+  let data = options.data ?? new Uint8Array(0);
+  const isJson = isJsonContentType(options.contentType);
+  if (isJson && data.length > 0) {
+    data = validateJsonCreate(data, true);
+  }
+  const appendCount = data.length > 0 ? 1 : 0;
+  const nextOffset = formatOffset(appendCount, data.length);
+  return { data, appendCount, nextOffset };
+}
+var MemoryStore = class {
+  streams = /* @__PURE__ */ new Map();
+  put(path, options) {
+    const existing = this.streams.get(path);
+    if (existing) {
+      validateIdempotentCreate(existing.metadata, options);
+      return Promise.resolve({
+        created: false,
+        nextOffset: existing.nextOffset
+      });
+    }
+    const { data, appendCount, nextOffset } = prepareInitialData(options);
+    const stream = {
+      metadata: {
+        path,
+        contentType: options.contentType,
+        ttlSeconds: options.ttlSeconds,
+        expiresAt: options.expiresAt,
+        createdAt: Date.now()
+      },
+      data,
+      nextOffset,
+      lastSeq: void 0,
+      appendCount,
+      waiters: []
+    };
+    this.streams.set(path, stream);
+    return Promise.resolve({ created: true, nextOffset });
+  }
+  append(path, data, options) {
+    const stream = this.streams.get(path);
+    if (!stream) {
+      return Promise.reject(new StreamNotFoundError(path));
+    }
+    const streamNormalized = normalizeContentType(stream.metadata.contentType);
+    if (options?.contentType) {
+      const reqNormalized = normalizeContentType(options.contentType);
+      if (streamNormalized !== reqNormalized) {
+        return Promise.reject(
+          new ContentTypeMismatchError(streamNormalized, reqNormalized)
+        );
+      }
+    }
+    if (options?.seq !== void 0 && stream.lastSeq !== void 0 && options.seq <= stream.lastSeq) {
+      return Promise.reject(
+        new SequenceConflictError(`> ${stream.lastSeq}`, options.seq)
+      );
+    }
+    const isJson = isJsonContentType(stream.metadata.contentType);
+    let newData;
+    if (isJson) {
+      newData = processJsonAppend(stream.data, data);
+    } else {
+      newData = new Uint8Array(stream.data.length + data.length);
+      newData.set(stream.data);
+      newData.set(data, stream.data.length);
+    }
+    stream.appendCount++;
+    const nextOffset = formatOffset(stream.appendCount, newData.length);
+    if (options?.seq !== void 0) {
+      stream.lastSeq = options.seq;
+    }
+    stream.data = newData;
+    stream.nextOffset = nextOffset;
+    this.notifyWaiters(stream);
+    return Promise.resolve({ nextOffset });
+  }
+  get(path, options) {
+    const stream = this.streams.get(path);
+    if (!stream) {
+      return Promise.reject(new StreamNotFoundError(path));
+    }
+    const startOffset = options?.offset ?? initialOffset();
+    const byteOffset = offsetToBytePos(startOffset);
+    const messages = [];
+    if (byteOffset < stream.data.length) {
+      const data = stream.data.slice(byteOffset);
+      messages.push({
+        offset: startOffset,
+        timestamp: Date.now(),
+        data
+      });
+    }
+    return Promise.resolve({
+      messages,
+      nextOffset: stream.nextOffset,
+      upToDate: true,
+      cursor: generateCursor(),
+      etag: generateETag(path, startOffset, stream.nextOffset),
+      contentType: stream.metadata.contentType
+    });
+  }
+  head(path) {
+    const stream = this.streams.get(path);
+    if (!stream) {
+      return Promise.resolve(null);
+    }
+    return Promise.resolve({
+      contentType: stream.metadata.contentType,
+      nextOffset: stream.nextOffset,
+      etag: generateETag(path, initialOffset(), stream.nextOffset)
+    });
+  }
+  delete(path) {
+    const stream = this.streams.get(path);
+    if (stream) {
+      const effect = Effect_exports.forEach(
+        stream.waiters,
+        (waiter) => Deferred_exports.succeed(waiter.deferred, { messages: [], timedOut: false })
+      );
+      Effect_exports.runSync(effect);
+    }
+    this.streams.delete(path);
+    return Promise.resolve();
+  }
+  has(path) {
+    return this.streams.has(path);
+  }
+  waitForData(path, offset, timeoutMs) {
+    const stream = this.streams.get(path);
+    if (!stream) {
+      return Promise.reject(new StreamNotFoundError(path));
+    }
+    const byteOffset = offsetToBytePos(offset);
+    if (byteOffset < stream.data.length) {
+      const data = stream.data.slice(byteOffset);
+      return Promise.resolve({
+        messages: [{ offset, timestamp: Date.now(), data }],
+        timedOut: false
+      });
+    }
+    const effect = Effect_exports.gen(this, function* () {
+      const deferred = yield* Deferred_exports.make();
+      const waiter = { deferred, offset };
+      stream.waiters.push(waiter);
+      const timeout = Effect_exports.as(
+        Effect_exports.delay(
+          Effect_exports.sync(() => {
+          }),
+          timeoutMs
+        ),
+        { messages: [], timedOut: true }
+      );
+      const result = yield* Effect_exports.race(Deferred_exports.await(deferred), timeout);
+      const index = stream.waiters.indexOf(waiter);
+      if (index !== -1) {
+        stream.waiters.splice(index, 1);
+      }
+      return result;
+    });
+    return Effect_exports.runPromise(effect);
+  }
+  formatResponse(path, messages) {
+    const stream = this.streams.get(path);
+    if (!stream) {
+      return new Uint8Array(0);
+    }
+    if (messages.length === 0) {
+      const isJson2 = isJsonContentType(stream.metadata.contentType);
+      return isJson2 ? new TextEncoder().encode("[]") : new Uint8Array(0);
+    }
+    const combined = new Uint8Array(
+      messages.reduce((acc, m) => acc + m.data.length, 0)
+    );
+    let offset = 0;
+    for (const message of messages) {
+      combined.set(message.data, offset);
+      offset += message.data.length;
+    }
+    const isJson = isJsonContentType(stream.metadata.contentType);
+    return isJson ? formatJsonResponse(combined) : combined;
+  }
+  notifyWaiters(stream) {
+    const waiters = [...stream.waiters];
+    stream.waiters = [];
+    const effect = Effect_exports.forEach(waiters, (waiter) => {
+      const byteOffset = offsetToBytePos(waiter.offset);
+      if (byteOffset < stream.data.length) {
+        const data = stream.data.slice(byteOffset);
+        return Deferred_exports.succeed(waiter.deferred, {
+          messages: [{ offset: waiter.offset, timestamp: Date.now(), data }],
+          timedOut: false
+        });
+      }
+      stream.waiters.push(waiter);
+      return Effect_exports.void;
+    });
+    Effect_exports.runSync(effect);
+  }
+};
+
+export {
+  MemoryStore
+};