@cloudwerk/durable-object 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Squirrelsoft Dev Tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,736 @@
+import { ZodType } from 'zod';
+
+/**
+ * @cloudwerk/durable-object - Type Definitions
+ *
+ * Core types for Durable Objects with native Cloudflare RPC support.
+ */
+
+/**
+ * Type that can be either a value or a Promise of that value.
+ * Used throughout the durable-object package for async-friendly APIs.
+ */
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Supported file extensions for durable object definitions.
+ */
+type SupportedExtension = '.ts' | '.tsx' | '.js' | '.jsx';
+/**
+ * Context available to all durable object handlers.
+ * Provides access to storage, SQL, and WebSocket management.
+ *
+ * @example
+ * ```typescript
+ * export default defineDurableObject<CounterState>({
+ *   async init(ctx) {
+ *     // Access SQLite storage
+ *     ctx.sql.run(`CREATE TABLE IF NOT EXISTS logs (id INTEGER PRIMARY KEY, action TEXT)`)
+ *     return { value: 0 }
+ *   }
+ * })
+ * ```
+ */
+interface DurableObjectContext {
+    /** Persistent key-value storage */
+    storage: DurableObjectStorage;
+    /** SQLite storage (if enabled) */
+    sql: SqlStorage;
+    /** Unique identifier for this durable object instance */
+    id: DurableObjectId;
+    /**
+     * Get all WebSocket connections, optionally filtered by tag.
+     * @param tag - Optional tag to filter WebSockets
+     */
+    getWebSockets(tag?: string): WebSocket[];
+    /**
+     * Accept a WebSocket connection with optional tags for grouping.
+     * @param ws - The WebSocket to accept
+     * @param tags - Optional tags for filtering later
+     */
+    acceptWebSocket(ws: WebSocket, tags?: string[]): void;
+}
+/**
+ * Handler context with state access.
+ * `this` is bound to this context in all handler methods.
+ *
+ * @typeParam TState - The state type for this durable object
+ *
+ * @example
+ * ```typescript
+ * export default defineDurableObject<CounterState>({
+ *   methods: {
+ *     async increment(amount = 1) {
+ *       this.state.value += amount  // Access state via this
+ *       this.ctx.sql.run(`INSERT INTO logs (action) VALUES ('increment')`)
+ *       return this.state.value
+ *     }
+ *   }
+ * })
+ * ```
+ */
+interface DurableObjectHandlerContext<TState = unknown> {
+    /** Current state of the durable object */
+    state: TState;
+    /** Context with storage, SQL, and WebSocket access */
+    ctx: DurableObjectContext;
+}
+/**
+ * Durable Object storage interface for key-value persistence.
+ */
+interface DurableObjectStorage {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+    list<T = unknown>(options?: DurableObjectStorageListOptions): Promise<Map<string, T>>;
+    put<T>(key: string, value: T): Promise<void>;
+    put<T>(entries: Record<string, T>): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    delete(keys: string[]): Promise<number>;
+    deleteAll(): Promise<void>;
+    transaction<T>(closure: (txn: DurableObjectTransaction) => Promise<T>): Promise<T>;
+    getAlarm(): Promise<number | null>;
+    setAlarm(scheduledTime: number | Date): Promise<void>;
+    deleteAlarm(): Promise<void>;
+    sync(): Promise<void>;
+}
+/**
+ * Options for listing storage keys.
+ */
+interface DurableObjectStorageListOptions {
+    start?: string;
+    startAfter?: string;
+    end?: string;
+    prefix?: string;
+    reverse?: boolean;
+    limit?: number;
+}
+/**
+ * Transaction interface for atomic operations.
+ */
+interface DurableObjectTransaction {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+    list<T = unknown>(options?: DurableObjectStorageListOptions): Promise<Map<string, T>>;
+    put<T>(key: string, value: T): Promise<void>;
+    put<T>(entries: Record<string, T>): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    delete(keys: string[]): Promise<number>;
+    rollback(): void;
+}
+/**
+ * SQLite storage interface for relational data.
+ */
+interface SqlStorage {
+    exec(query: string): SqlStorageCursor;
+    run(query: string, ...bindings: unknown[]): void;
+}
+/**
+ * Cursor for iterating SQL results.
+ */
+interface SqlStorageCursor {
+    [Symbol.iterator](): IterableIterator<Record<string, unknown>>;
+    toArray(): Record<string, unknown>[];
+    one(): Record<string, unknown> | null;
+    raw<T extends unknown[] = unknown[]>(): IterableIterator<T>;
+    columnNames: string[];
+    rowsRead: number;
+    rowsWritten: number;
+}
+/**
+ * Unique identifier for a durable object instance.
+ */
+interface DurableObjectId {
+    toString(): string;
+    equals(other: DurableObjectId): boolean;
+    name?: string;
+}
+/**
+ * Namespace for accessing durable object stubs.
+ */
+interface DurableObjectNamespace<T = unknown> {
+    idFromName(name: string): DurableObjectId;
+    idFromString(id: string): DurableObjectId;
+    newUniqueId(): DurableObjectId;
+    get(id: DurableObjectId): DurableObjectStub<T>;
+}
+/**
+ * Stub for interacting with a durable object instance.
+ * Methods defined in `defineDurableObject({ methods })` are directly callable via native RPC.
+ */
+interface DurableObjectStub<T = unknown> {
+    id: DurableObjectId;
+    name?: string;
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Configuration for defineDurableObject().
+ *
+ * @typeParam TState - The state type managed by this durable object
+ * @typeParam TEnv - The environment bindings type
+ *
+ * @example
+ * ```typescript
+ * interface CounterState {
+ *   value: number
+ * }
+ *
+ * export default defineDurableObject<CounterState>({
+ *   sqlite: true,
+ *
+ *   async init(ctx) {
+ *     ctx.sql.run(`CREATE TABLE IF NOT EXISTS logs (id INTEGER PRIMARY KEY)`)
+ *     return { value: 0 }
+ *   },
+ *
+ *   methods: {
+ *     async increment(amount = 1) {
+ *       this.state.value += amount
+ *       return this.state.value
+ *     },
+ *
+ *     async getValue() {
+ *       return this.state.value
+ *     },
+ *   },
+ *
+ *   async fetch(request) {
+ *     return new Response(`Counter: ${this.state.value}`)
+ *   },
+ * })
+ * ```
+ */
+interface DurableObjectConfig<TState = unknown, TEnv = unknown> {
+    /**
+     * Optional name override.
+     * By default, the name is derived from the filename.
+     * - `app/objects/counter.ts` -> `counter`
+     * - `app/objects/chat-room.ts` -> `chatRoom`
+     */
+    name?: string;
+    /**
+     * Enable SQLite storage for this durable object.
+     * When true, `ctx.sql` will be available for SQL operations.
+     * @default false
+     */
+    sqlite?: boolean;
+    /**
+     * Optional Zod schema for runtime validation of state.
+     */
+    schema?: ZodType<TState>;
+    /**
+     * Initialize state on first access to this durable object.
+     * Called once when the durable object is first created or hydrated.
+     *
+     * @param ctx - Context with storage, SQL, and WebSocket access
+     * @param env - Environment bindings
+     * @returns Initial state or Promise resolving to initial state
+     */
+    init?: (ctx: DurableObjectContext, env: TEnv) => Awaitable<TState>;
+    /**
+     * RPC methods callable directly on the durable object stub.
+     * These become native Cloudflare RPC methods (no HTTP overhead).
+     *
+     * @example
+     * ```typescript
+     * methods: {
+     *   async increment(amount = 1) {
+     *     this.state.value += amount
+     *     return this.state.value
+     *   }
+     * }
+     *
+     * // Usage:
+     * const stub = env.COUNTER.get(id)
+     * const value = await stub.increment(5)  // Direct RPC call
+     * ```
+     */
+    methods?: {
+        [name: string]: (this: DurableObjectHandlerContext<TState>, ...args: unknown[]) => Awaitable<unknown>;
+    };
+    /**
+     * HTTP request handler.
+     * Called when the durable object receives an HTTP request via stub.fetch().
+     *
+     * @param request - The incoming HTTP request
+     * @param env - Environment bindings
+     * @returns Response or Promise resolving to Response
+     */
+    fetch?: (this: DurableObjectHandlerContext<TState>, request: Request, env: TEnv) => Awaitable<Response>;
+    /**
+     * WebSocket message handler.
+     * Called when a WebSocket message is received.
+     *
+     * @param ws - The WebSocket that sent the message
+     * @param message - The message content (string or binary)
+     */
+    webSocketMessage?: (this: DurableObjectHandlerContext<TState>, ws: WebSocket, message: string | ArrayBuffer) => Awaitable<void>;
+    /**
+     * WebSocket close handler.
+     * Called when a WebSocket connection closes.
+     *
+     * @param ws - The WebSocket that closed
+     * @param code - Close code
+     * @param reason - Close reason
+     */
+    webSocketClose?: (this: DurableObjectHandlerContext<TState>, ws: WebSocket, code: number, reason: string) => Awaitable<void>;
+    /**
+     * WebSocket error handler.
+     * Called when a WebSocket error occurs.
+     *
+     * @param ws - The WebSocket with the error
+     * @param error - The error that occurred
+     */
+    webSocketError?: (this: DurableObjectHandlerContext<TState>, ws: WebSocket, error: Error) => Awaitable<void>;
+    /**
+     * Alarm handler.
+     * Called when a scheduled alarm fires.
+     * Set alarms using `ctx.storage.setAlarm()`.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   async init(ctx) {
+     *     // Schedule alarm for 1 hour from now
+     *     await ctx.storage.setAlarm(Date.now() + 60 * 60 * 1000)
+     *     return { lastCleanup: Date.now() }
+     *   },
+     *
+     *   async alarm() {
+     *     // Perform periodic cleanup
+     *     this.state.lastCleanup = Date.now()
+     *     // Reschedule for next hour
+     *     await this.ctx.storage.setAlarm(Date.now() + 60 * 60 * 1000)
+     *   }
+     * }
+     * ```
+     */
+    alarm?: (this: DurableObjectHandlerContext<TState>) => Awaitable<void>;
+}
+/**
+ * A defined durable object, returned by defineDurableObject().
+ *
+ * @typeParam TState - The state type managed by this durable object
+ * @typeParam TEnv - The environment bindings type
+ */
+interface DurableObjectDefinition<TState = unknown, TEnv = unknown> {
+    /** Internal marker identifying this as a durable object definition */
+    readonly __brand: 'cloudwerk-durable-object';
+    /** Object name (derived from filename or explicitly set) */
+    readonly name: string | undefined;
+    /** Whether SQLite storage is enabled */
+    readonly sqlite: boolean;
+    /** Zod schema for state validation (if provided) */
+    readonly schema: ZodType<TState> | undefined;
+    /** The full configuration object */
+    readonly config: DurableObjectConfig<TState, TEnv>;
+}
+/**
+ * A scanned durable object file from the app/objects/ directory.
+ */
+interface ScannedDurableObject {
+    /** Relative path from app/objects/ (e.g., 'counter.ts') */
+    relativePath: string;
+    /** Absolute filesystem path */
+    absolutePath: string;
+    /** File name without extension (e.g., 'counter') */
+    name: string;
+    /** File extension (e.g., '.ts') */
+    extension: SupportedExtension;
+}
+/**
+ * Result of scanning the app/objects/ directory.
+ */
+interface DurableObjectScanResult {
+    /** All discovered durable object files */
+    durableObjects: ScannedDurableObject[];
+}
+/**
+ * A compiled durable object entry in the manifest.
+ */
+interface DurableObjectEntry {
+    /** Object name derived from filename (e.g., 'counter', 'chatRoom') */
+    name: string;
+    /** Binding name for wrangler.toml (e.g., 'COUNTER', 'CHAT_ROOM') */
+    bindingName: string;
+    /** Class name for the generated DO class (e.g., 'Counter', 'ChatRoom') */
+    className: string;
+    /** Relative path to the definition file */
+    filePath: string;
+    /** Absolute path to the definition file */
+    absolutePath: string;
+    /** Path to the generated DO class file */
+    generatedPath: string;
+    /** Whether SQLite storage is enabled */
+    sqlite: boolean;
+    /** Whether fetch handler is defined */
+    hasFetch: boolean;
+    /** Whether WebSocket handlers are defined */
+    hasWebSocket: boolean;
+    /** Whether alarm handler is defined */
+    hasAlarm: boolean;
+    /** RPC method names extracted from methods config */
+    methodNames: string[];
+}
+/**
+ * Validation error for a durable object definition.
+ */
+interface DurableObjectValidationError {
+    /** Durable object file path */
+    file: string;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: 'NO_HANDLER' | 'INVALID_CONFIG' | 'DUPLICATE_NAME' | 'INVALID_NAME' | 'INVALID_DEFINITION';
+}
+/**
+ * Validation warning for a durable object definition.
+ */
+interface DurableObjectValidationWarning {
+    /** Durable object file path */
+    file: string;
+    /** Warning message */
+    message: string;
+    /** Warning code */
+    code: 'NO_INIT' | 'NO_METHODS' | 'SQLITE_WITHOUT_INIT';
+}
+/**
+ * Complete durable object manifest generated during build.
+ */
+interface DurableObjectManifest {
+    /** All compiled durable object entries */
+    durableObjects: DurableObjectEntry[];
+    /** Validation errors (object won't be registered) */
+    errors: DurableObjectValidationError[];
+    /** Validation warnings (object will be registered with warning) */
+    warnings: DurableObjectValidationWarning[];
+    /** When the manifest was generated */
+    generatedAt: Date;
+    /** Root directory of the app */
+    rootDir: string;
+}
+/**
+ * A Cloudflare Durable Object migration for wrangler.toml.
+ */
+interface DurableObjectMigration {
+    /** Migration tag (e.g., 'v1', 'v2') */
+    tag: string;
+    /** New classes to create */
+    new_classes?: string[];
+    /** New classes that use SQLite storage */
+    new_sqlite_classes?: string[];
+    /** Classes to rename */
+    renamed_classes?: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** Classes to delete */
+    deleted_classes?: string[];
+}
+/**
+ * Options for building the durable object manifest.
+ */
+interface BuildDurableObjectManifestOptions {
+    /** Application name for prefixing (e.g., 'cloudwerk') */
+    appName?: string;
+    /** Whether to validate definitions at build time */
+    validate?: boolean;
+    /** Output directory for generated files */
+    outputDir?: string;
+}
+
+/**
+ * @cloudwerk/durable-object - Error Classes
+ *
+ * Custom error classes for Durable Object operations.
+ */
+/**
+ * Base error class for durable object-related errors.
+ */
+declare class DurableObjectError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when durable object configuration is invalid.
+ *
+ * @example
+ * ```typescript
+ * // Thrown when no handlers are defined
+ * export default defineDurableObject({
+ *   // Missing methods, fetch, alarm, or WebSocket handlers
+ * })
+ * ```
+ */
+declare class DurableObjectConfigError extends DurableObjectError {
+    /** The configuration field that is invalid */
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/**
+ * Error thrown when no handler is defined for a durable object.
+ */
+declare class DurableObjectNoHandlerError extends DurableObjectError {
+    constructor(objectName: string);
+}
+/**
+ * Error thrown when accessing a durable object outside of request context.
+ */
+declare class DurableObjectContextError extends DurableObjectError {
+    constructor();
+}
+/**
+ * Error thrown when a durable object binding is not found.
+ *
+ * @example
+ * ```typescript
+ * import { durableObjects } from '@cloudwerk/bindings'
+ *
+ * // Throws if COUNTER binding doesn't exist in environment
+ * const counter = durableObjects.counter
+ * ```
+ */
+declare class DurableObjectNotFoundError extends DurableObjectError {
+    /** The durable object name that was not found */
+    readonly objectName: string;
+    /** Available durable object names */
+    readonly availableObjects: string[];
+    constructor(objectName: string, availableObjects: string[]);
+}
+/**
+ * Error thrown when state initialization fails.
+ */
+declare class DurableObjectStateError extends DurableObjectError {
+    /** The durable object name */
+    readonly objectName: string;
+    constructor(objectName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when state validation fails.
+ */
+declare class DurableObjectSchemaValidationError extends DurableObjectError {
+    /** The validation errors from Zod */
+    readonly validationErrors: unknown[];
+    constructor(message: string, validationErrors: unknown[]);
+}
+/**
+ * Error thrown when an RPC method call fails.
+ */
+declare class DurableObjectRPCError extends DurableObjectError {
+    /** The durable object name */
+    readonly objectName: string;
+    /** The method that was called */
+    readonly methodName: string;
+    constructor(objectName: string, methodName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when an RPC method is not found.
+ */
+declare class DurableObjectMethodNotFoundError extends DurableObjectError {
+    /** The durable object name */
+    readonly objectName: string;
+    /** The method that was not found */
+    readonly methodName: string;
+    /** Available method names */
+    readonly availableMethods: string[];
+    constructor(objectName: string, methodName: string, availableMethods: string[]);
+}
+/**
+ * Error thrown when an alarm operation fails.
+ */
+declare class DurableObjectAlarmError extends DurableObjectError {
+    /** The durable object name */
+    readonly objectName: string;
+    constructor(objectName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when a WebSocket operation fails.
+ */
+declare class DurableObjectWebSocketError extends DurableObjectError {
+    /** The durable object name */
+    readonly objectName: string;
+    constructor(objectName: string, message: string, options?: ErrorOptions);
+}
+
+/**
+ * @cloudwerk/durable-object - defineDurableObject()
+ *
+ * Factory function for creating Durable Object definitions with native RPC support.
+ */
+
+/**
+ * Define a Durable Object with native Cloudflare RPC support.
+ *
+ * This function creates a durable object definition that will be automatically
+ * discovered and registered by Cloudwerk during build. The build process generates
+ * a class extending Cloudflare's DurableObject with native RPC methods.
+ *
+ * @typeParam TState - The state type managed by this durable object
+ * @typeParam TEnv - The environment bindings type
+ * @param config - Durable object configuration
+ * @returns Durable object definition
+ *
+ * @example
+ * ```typescript
+ * // app/objects/counter.ts
+ * import { defineDurableObject } from '@cloudwerk/durable-object'
+ *
+ * interface CounterState {
+ *   value: number
+ * }
+ *
+ * export default defineDurableObject<CounterState>({
+ *   sqlite: true,
+ *
+ *   async init(ctx) {
+ *     ctx.sql.run(`CREATE TABLE IF NOT EXISTS logs (id INTEGER PRIMARY KEY, action TEXT)`)
+ *     return { value: 0 }
+ *   },
+ *
+ *   methods: {
+ *     async increment(amount = 1) {
+ *       this.state.value += amount
+ *       this.ctx.sql.run(`INSERT INTO logs (action) VALUES ('increment')`)
+ *       return this.state.value
+ *     },
+ *
+ *     async getValue() {
+ *       return this.state.value
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage in route handler:
+ * import { durableObjects } from '@cloudwerk/bindings'
+ *
+ * export async function POST(request: Request, { params }: Context) {
+ *   const id = durableObjects.Counter.idFromName(params.id)
+ *   const stub = durableObjects.Counter.get(id)
+ *
+ *   // Native RPC - direct method calls!
+ *   const value = await stub.increment(5)
+ *
+ *   return Response.json({ value })
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With HTTP fetch handler
+ * import { defineDurableObject } from '@cloudwerk/durable-object'
+ *
+ * export default defineDurableObject<{ count: number }>({
+ *   init: () => ({ count: 0 }),
+ *
+ *   async fetch(request) {
+ *     const url = new URL(request.url)
+ *
+ *     if (url.pathname === '/increment') {
+ *       this.state.count++
+ *     }
+ *
+ *     return new Response(String(this.state.count))
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With WebSocket support
+ * import { defineDurableObject } from '@cloudwerk/durable-object'
+ *
+ * interface ChatState {
+ *   messages: string[]
+ * }
+ *
+ * export default defineDurableObject<ChatState>({
+ *   init: () => ({ messages: [] }),
+ *
+ *   async fetch(request) {
+ *     const upgradeHeader = request.headers.get('Upgrade')
+ *     if (upgradeHeader !== 'websocket') {
+ *       return new Response('Expected WebSocket', { status: 426 })
+ *     }
+ *
+ *     const pair = new WebSocketPair()
+ *     this.ctx.acceptWebSocket(pair[1])
+ *
+ *     return new Response(null, { status: 101, webSocket: pair[0] })
+ *   },
+ *
+ *   async webSocketMessage(ws, message) {
+ *     this.state.messages.push(String(message))
+ *
+ *     // Broadcast to all connected clients
+ *     for (const client of this.ctx.getWebSockets()) {
+ *       client.send(String(message))
+ *     }
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With alarm handler
+ * import { defineDurableObject } from '@cloudwerk/durable-object'
+ *
+ * interface CleanupState {
+ *   lastCleanup: number
+ * }
+ *
+ * export default defineDurableObject<CleanupState>({
+ *   async init(ctx) {
+ *     // Schedule first alarm for 1 hour from now
+ *     await ctx.storage.setAlarm(Date.now() + 60 * 60 * 1000)
+ *     return { lastCleanup: Date.now() }
+ *   },
+ *
+ *   async alarm() {
+ *     // Perform periodic cleanup
+ *     this.state.lastCleanup = Date.now()
+ *
+ *     // Reschedule for next hour
+ *     await this.ctx.storage.setAlarm(Date.now() + 60 * 60 * 1000)
+ *   },
+ *
+ *   methods: {
+ *     getLastCleanup() {
+ *       return this.state.lastCleanup
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function defineDurableObject<TState = unknown, TEnv = unknown>(config: DurableObjectConfig<TState, TEnv>): DurableObjectDefinition<TState, TEnv>;
+/**
+ * Check if a value is a durable object definition created by defineDurableObject().
+ *
+ * @param value - Value to check
+ * @returns true if value is a DurableObjectDefinition
+ */
+declare function isDurableObjectDefinition(value: unknown): value is DurableObjectDefinition;
+/**
+ * Extract method names from a durable object definition.
+ *
+ * @param definition - The durable object definition
+ * @returns Array of method names
+ */
+declare function getMethodNames(definition: DurableObjectDefinition): string[];
+/**
+ * Check if a durable object definition has any handlers.
+ *
+ * @param definition - The durable object definition
+ * @returns true if at least one handler is defined
+ */
+declare function hasHandlers(definition: DurableObjectDefinition): boolean;
+/**
+ * Check if a durable object definition has WebSocket support.
+ *
+ * @param definition - The durable object definition
+ * @returns true if any WebSocket handler is defined
+ */
+declare function hasWebSocketSupport(definition: DurableObjectDefinition): boolean;
+
+export { type Awaitable, type BuildDurableObjectManifestOptions, DurableObjectAlarmError, type DurableObjectConfig, DurableObjectConfigError, type DurableObjectContext, DurableObjectContextError, type DurableObjectDefinition, type DurableObjectEntry, DurableObjectError, type DurableObjectHandlerContext, type DurableObjectId, type DurableObjectManifest, DurableObjectMethodNotFoundError, type DurableObjectMigration, type DurableObjectNamespace, DurableObjectNoHandlerError, DurableObjectNotFoundError, DurableObjectRPCError, type DurableObjectScanResult, DurableObjectSchemaValidationError, DurableObjectStateError, type DurableObjectStorage, type DurableObjectStorageListOptions, type DurableObjectStub, type DurableObjectTransaction, type DurableObjectValidationError, type DurableObjectValidationWarning, DurableObjectWebSocketError, type ScannedDurableObject, type SqlStorage, type SqlStorageCursor, type SupportedExtension, defineDurableObject, getMethodNames, hasHandlers, hasWebSocketSupport, isDurableObjectDefinition };

package/dist/index.js

@@ -0,0 +1,254 @@
+// src/errors.ts
+var DurableObjectError = class extends Error {
+  /** Error code for programmatic handling */
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "DurableObjectError";
+    this.code = code;
+  }
+};
+var DurableObjectConfigError = class extends DurableObjectError {
+  /** The configuration field that is invalid */
+  field;
+  constructor(message, field) {
+    super("CONFIG_ERROR", message);
+    this.name = "DurableObjectConfigError";
+    this.field = field;
+  }
+};
+var DurableObjectNoHandlerError = class extends DurableObjectError {
+  constructor(objectName) {
+    super(
+      "NO_HANDLER",
+      `Durable object '${objectName}' must define at least one handler (methods, fetch, alarm, or webSocketMessage)`
+    );
+    this.name = "DurableObjectNoHandlerError";
+  }
+};
+var DurableObjectContextError = class extends DurableObjectError {
+  constructor() {
+    super(
+      "CONTEXT_ERROR",
+      "Durable object accessed outside of request handler. Durable objects can only be accessed during request handling."
+    );
+    this.name = "DurableObjectContextError";
+  }
+};
+var DurableObjectNotFoundError = class extends DurableObjectError {
+  /** The durable object name that was not found */
+  objectName;
+  /** Available durable object names */
+  availableObjects;
+  constructor(objectName, availableObjects) {
+    const available = availableObjects.length > 0 ? `Available durable objects: ${availableObjects.join(", ")}` : "No durable objects are configured";
+    super(
+      "DURABLE_OBJECT_NOT_FOUND",
+      `Durable object '${objectName}' not found in environment. ${available}`
+    );
+    this.name = "DurableObjectNotFoundError";
+    this.objectName = objectName;
+    this.availableObjects = availableObjects;
+  }
+};
+var DurableObjectStateError = class extends DurableObjectError {
+  /** The durable object name */
+  objectName;
+  constructor(objectName, message, options) {
+    super("STATE_ERROR", `State error in durable object '${objectName}': ${message}`, options);
+    this.name = "DurableObjectStateError";
+    this.objectName = objectName;
+  }
+};
+var DurableObjectSchemaValidationError = class extends DurableObjectError {
+  /** The validation errors from Zod */
+  validationErrors;
+  constructor(message, validationErrors) {
+    super("VALIDATION_ERROR", message);
+    this.name = "DurableObjectSchemaValidationError";
+    this.validationErrors = validationErrors;
+  }
+};
+var DurableObjectRPCError = class extends DurableObjectError {
+  /** The durable object name */
+  objectName;
+  /** The method that was called */
+  methodName;
+  constructor(objectName, methodName, message, options) {
+    super(
+      "RPC_ERROR",
+      `RPC error calling '${methodName}' on durable object '${objectName}': ${message}`,
+      options
+    );
+    this.name = "DurableObjectRPCError";
+    this.objectName = objectName;
+    this.methodName = methodName;
+  }
+};
+var DurableObjectMethodNotFoundError = class extends DurableObjectError {
+  /** The durable object name */
+  objectName;
+  /** The method that was not found */
+  methodName;
+  /** Available method names */
+  availableMethods;
+  constructor(objectName, methodName, availableMethods) {
+    const available = availableMethods.length > 0 ? `Available methods: ${availableMethods.join(", ")}` : "No RPC methods are defined";
+    super(
+      "METHOD_NOT_FOUND",
+      `Method '${methodName}' not found on durable object '${objectName}'. ${available}`
+    );
+    this.name = "DurableObjectMethodNotFoundError";
+    this.objectName = objectName;
+    this.methodName = methodName;
+    this.availableMethods = availableMethods;
+  }
+};
+var DurableObjectAlarmError = class extends DurableObjectError {
+  /** The durable object name */
+  objectName;
+  constructor(objectName, message, options) {
+    super("ALARM_ERROR", `Alarm error in durable object '${objectName}': ${message}`, options);
+    this.name = "DurableObjectAlarmError";
+    this.objectName = objectName;
+  }
+};
+var DurableObjectWebSocketError = class extends DurableObjectError {
+  /** The durable object name */
+  objectName;
+  constructor(objectName, message, options) {
+    super(
+      "WEBSOCKET_ERROR",
+      `WebSocket error in durable object '${objectName}': ${message}`,
+      options
+    );
+    this.name = "DurableObjectWebSocketError";
+    this.objectName = objectName;
+  }
+};
+
+// src/define-durable-object.ts
+var NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+var RESERVED_METHODS = /* @__PURE__ */ new Set([
+  "fetch",
+  "alarm",
+  "webSocketMessage",
+  "webSocketClose",
+  "webSocketError",
+  "constructor",
+  "init"
+]);
+function validateConfig(config) {
+  const hasHandler = config.fetch !== void 0 || config.alarm !== void 0 || config.webSocketMessage !== void 0 || config.methods !== void 0 && Object.keys(config.methods).length > 0;
+  if (!hasHandler) {
+    throw new DurableObjectNoHandlerError(config.name || "unknown");
+  }
+  if (config.name !== void 0) {
+    if (typeof config.name !== "string" || config.name.length === 0) {
+      throw new DurableObjectConfigError("name must be a non-empty string", "name");
+    }
+    if (!NAME_PATTERN.test(config.name)) {
+      throw new DurableObjectConfigError(
+        "name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens",
+        "name"
+      );
+    }
+  }
+  if (config.sqlite !== void 0 && typeof config.sqlite !== "boolean") {
+    throw new DurableObjectConfigError("sqlite must be a boolean", "sqlite");
+  }
+  if (config.methods !== void 0) {
+    if (typeof config.methods !== "object" || config.methods === null) {
+      throw new DurableObjectConfigError("methods must be an object", "methods");
+    }
+    for (const methodName of Object.keys(config.methods)) {
+      if (RESERVED_METHODS.has(methodName)) {
+        throw new DurableObjectConfigError(
+          `'${methodName}' is a reserved method name and cannot be used in methods config`,
+          "methods"
+        );
+      }
+      if (typeof config.methods[methodName] !== "function") {
+        throw new DurableObjectConfigError(
+          `methods.${methodName} must be a function`,
+          "methods"
+        );
+      }
+      if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(methodName)) {
+        throw new DurableObjectConfigError(
+          `'${methodName}' is not a valid method name. Method names must be valid JavaScript identifiers`,
+          "methods"
+        );
+      }
+    }
+  }
+  if (config.init !== void 0 && typeof config.init !== "function") {
+    throw new DurableObjectConfigError("init must be a function", "init");
+  }
+  if (config.fetch !== void 0 && typeof config.fetch !== "function") {
+    throw new DurableObjectConfigError("fetch must be a function", "fetch");
+  }
+  if (config.alarm !== void 0 && typeof config.alarm !== "function") {
+    throw new DurableObjectConfigError("alarm must be a function", "alarm");
+  }
+  if (config.webSocketMessage !== void 0 && typeof config.webSocketMessage !== "function") {
+    throw new DurableObjectConfigError(
+      "webSocketMessage must be a function",
+      "webSocketMessage"
+    );
+  }
+  if (config.webSocketClose !== void 0 && typeof config.webSocketClose !== "function") {
+    throw new DurableObjectConfigError("webSocketClose must be a function", "webSocketClose");
+  }
+  if (config.webSocketError !== void 0 && typeof config.webSocketError !== "function") {
+    throw new DurableObjectConfigError("webSocketError must be a function", "webSocketError");
+  }
+}
+function defineDurableObject(config) {
+  validateConfig(config);
+  const definition = {
+    __brand: "cloudwerk-durable-object",
+    name: config.name,
+    sqlite: config.sqlite ?? false,
+    schema: config.schema,
+    config
+  };
+  return definition;
+}
+function isDurableObjectDefinition(value) {
+  return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "cloudwerk-durable-object";
+}
+function getMethodNames(definition) {
+  const methods = definition.config.methods;
+  if (!methods) {
+    return [];
+  }
+  return Object.keys(methods);
+}
+function hasHandlers(definition) {
+  const { config } = definition;
+  return config.fetch !== void 0 || config.alarm !== void 0 || config.webSocketMessage !== void 0 || config.methods !== void 0 && Object.keys(config.methods).length > 0;
+}
+function hasWebSocketSupport(definition) {
+  const { config } = definition;
+  return config.webSocketMessage !== void 0 || config.webSocketClose !== void 0 || config.webSocketError !== void 0;
+}
+export {
+  DurableObjectAlarmError,
+  DurableObjectConfigError,
+  DurableObjectContextError,
+  DurableObjectError,
+  DurableObjectMethodNotFoundError,
+  DurableObjectNoHandlerError,
+  DurableObjectNotFoundError,
+  DurableObjectRPCError,
+  DurableObjectSchemaValidationError,
+  DurableObjectStateError,
+  DurableObjectWebSocketError,
+  defineDurableObject,
+  getMethodNames,
+  hasHandlers,
+  hasWebSocketSupport,
+  isDurableObjectDefinition
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/define-durable-object.ts"],"sourcesContent":["/**\n * @cloudwerk/durable-object - Error Classes\n *\n * Custom error classes for Durable Object operations.\n */\n\n// ============================================================================\n// Base Error\n// ============================================================================\n\n/**\n * Base error class for durable object-related errors.\n */\nexport class DurableObjectError extends Error {\n  /** Error code for programmatic handling */\n  readonly code: string\n\n  constructor(code: string, message: string, options?: ErrorOptions) {\n    super(message, options)\n    this.name = 'DurableObjectError'\n    this.code = code\n  }\n}\n\n// ============================================================================\n// Configuration Errors\n// ============================================================================\n\n/**\n * Error thrown when durable object configuration is invalid.\n *\n * @example\n * ```typescript\n * // Thrown when no handlers are defined\n * export default defineDurableObject({\n *   // Missing methods, fetch, alarm, or WebSocket handlers\n * })\n * ```\n */\nexport class DurableObjectConfigError extends DurableObjectError {\n  /** The configuration field that is invalid */\n  readonly field?: string\n\n  constructor(message: string, field?: string) {\n    super('CONFIG_ERROR', message)\n    this.name = 'DurableObjectConfigError'\n    this.field = field\n  }\n}\n\n/**\n * Error thrown when no handler is defined for a durable object.\n */\nexport class DurableObjectNoHandlerError extends DurableObjectError {\n  constructor(objectName: string) {\n    super(\n      'NO_HANDLER',\n      `Durable object '${objectName}' must define at least one handler (methods, fetch, alarm, or webSocketMessage)`\n    )\n    this.name = 'DurableObjectNoHandlerError'\n  }\n}\n\n// ============================================================================\n// Runtime Errors\n// ============================================================================\n\n/**\n * Error thrown when accessing a durable object outside of request context.\n */\nexport class DurableObjectContextError extends DurableObjectError {\n  constructor() {\n    super(\n      'CONTEXT_ERROR',\n      'Durable object accessed outside of request handler. Durable objects can only be accessed during request handling.'\n    )\n    this.name = 'DurableObjectContextError'\n  }\n}\n\n/**\n * Error thrown when a durable object binding is not found.\n *\n * @example\n * ```typescript\n * import { durableObjects } from '@cloudwerk/bindings'\n *\n * // Throws if COUNTER binding doesn't exist in environment\n * const counter = durableObjects.counter\n * ```\n */\nexport class DurableObjectNotFoundError extends DurableObjectError {\n  /** The durable object name that was not found */\n  readonly objectName: string\n\n  /** Available durable object names */\n  readonly availableObjects: string[]\n\n  constructor(objectName: string, availableObjects: string[]) {\n    const available =\n      availableObjects.length > 0\n        ? `Available durable objects: ${availableObjects.join(', ')}`\n        : 'No durable objects are configured'\n\n    super(\n      'DURABLE_OBJECT_NOT_FOUND',\n      `Durable object '${objectName}' not found in environment. ${available}`\n    )\n    this.name = 'DurableObjectNotFoundError'\n    this.objectName = objectName\n    this.availableObjects = availableObjects\n  }\n}\n\n// ============================================================================\n// State Errors\n// ============================================================================\n\n/**\n * Error thrown when state initialization fails.\n */\nexport class DurableObjectStateError extends DurableObjectError {\n  /** The durable object name */\n  readonly objectName: string\n\n  constructor(objectName: string, message: string, options?: ErrorOptions) {\n    super('STATE_ERROR', `State error in durable object '${objectName}': ${message}`, options)\n    this.name = 'DurableObjectStateError'\n    this.objectName = objectName\n  }\n}\n\n/**\n * Error thrown when state validation fails.\n */\nexport class DurableObjectSchemaValidationError extends DurableObjectError {\n  /** The validation errors from Zod */\n  readonly validationErrors: unknown[]\n\n  constructor(message: string, validationErrors: unknown[]) {\n    super('VALIDATION_ERROR', message)\n    this.name = 'DurableObjectSchemaValidationError'\n    this.validationErrors = validationErrors\n  }\n}\n\n// ============================================================================\n// RPC Errors\n// ============================================================================\n\n/**\n * Error thrown when an RPC method call fails.\n */\nexport class DurableObjectRPCError extends DurableObjectError {\n  /** The durable object name */\n  readonly objectName: string\n\n  /** The method that was called */\n  readonly methodName: string\n\n  constructor(objectName: string, methodName: string, message: string, options?: ErrorOptions) {\n    super(\n      'RPC_ERROR',\n      `RPC error calling '${methodName}' on durable object '${objectName}': ${message}`,\n      options\n    )\n    this.name = 'DurableObjectRPCError'\n    this.objectName = objectName\n    this.methodName = methodName\n  }\n}\n\n/**\n * Error thrown when an RPC method is not found.\n */\nexport class DurableObjectMethodNotFoundError extends DurableObjectError {\n  /** The durable object name */\n  readonly objectName: string\n\n  /** The method that was not found */\n  readonly methodName: string\n\n  /** Available method names */\n  readonly availableMethods: string[]\n\n  constructor(objectName: string, methodName: string, availableMethods: string[]) {\n    const available =\n      availableMethods.length > 0\n        ? `Available methods: ${availableMethods.join(', ')}`\n        : 'No RPC methods are defined'\n\n    super(\n      'METHOD_NOT_FOUND',\n      `Method '${methodName}' not found on durable object '${objectName}'. ${available}`\n    )\n    this.name = 'DurableObjectMethodNotFoundError'\n    this.objectName = objectName\n    this.methodName = methodName\n    this.availableMethods = availableMethods\n  }\n}\n\n// ============================================================================\n// Alarm Errors\n// ============================================================================\n\n/**\n * Error thrown when an alarm operation fails.\n */\nexport class DurableObjectAlarmError extends DurableObjectError {\n  /** The durable object name */\n  readonly objectName: string\n\n  constructor(objectName: string, message: string, options?: ErrorOptions) {\n    super('ALARM_ERROR', `Alarm error in durable object '${objectName}': ${message}`, options)\n    this.name = 'DurableObjectAlarmError'\n    this.objectName = objectName\n  }\n}\n\n// ============================================================================\n// WebSocket Errors\n// ============================================================================\n\n/**\n * Error thrown when a WebSocket operation fails.\n */\nexport class DurableObjectWebSocketError extends DurableObjectError {\n  /** The durable object name */\n  readonly objectName: string\n\n  constructor(objectName: string, message: string, options?: ErrorOptions) {\n    super(\n      'WEBSOCKET_ERROR',\n      `WebSocket error in durable object '${objectName}': ${message}`,\n      options\n    )\n    this.name = 'DurableObjectWebSocketError'\n    this.objectName = objectName\n  }\n}\n","/**\n * @cloudwerk/durable-object - defineDurableObject()\n *\n * Factory function for creating Durable Object definitions with native RPC support.\n */\n\nimport type { DurableObjectConfig, DurableObjectDefinition } from './types.js'\nimport { DurableObjectConfigError, DurableObjectNoHandlerError } from './errors.js'\n\n// ============================================================================\n// Validation\n// ============================================================================\n\n/**\n * Valid name pattern for durable objects.\n * Must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.\n */\nconst NAME_PATTERN = /^[a-z][a-z0-9-]*$/\n\n/**\n * Reserved method names that cannot be used in the methods config.\n */\nconst RESERVED_METHODS = new Set([\n  'fetch',\n  'alarm',\n  'webSocketMessage',\n  'webSocketClose',\n  'webSocketError',\n  'constructor',\n  'init',\n])\n\n/**\n * Validate durable object configuration.\n *\n * @param config - Durable object configuration to validate\n * @throws DurableObjectConfigError if configuration is invalid\n * @throws DurableObjectNoHandlerError if no handler is defined\n */\nfunction validateConfig<TState, TEnv>(\n  config: DurableObjectConfig<TState, TEnv>\n): void {\n  // Must have at least one handler\n  const hasHandler =\n    config.fetch !== undefined ||\n    config.alarm !== undefined ||\n    config.webSocketMessage !== undefined ||\n    (config.methods !== undefined && Object.keys(config.methods).length > 0)\n\n  if (!hasHandler) {\n    throw new DurableObjectNoHandlerError(config.name || 'unknown')\n  }\n\n  // Validate name if provided\n  if (config.name !== undefined) {\n    if (typeof config.name !== 'string' || config.name.length === 0) {\n      throw new DurableObjectConfigError('name must be a non-empty string', 'name')\n    }\n\n    if (!NAME_PATTERN.test(config.name)) {\n      throw new DurableObjectConfigError(\n        'name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens',\n        'name'\n      )\n    }\n  }\n\n  // Validate sqlite flag\n  if (config.sqlite !== undefined && typeof config.sqlite !== 'boolean') {\n    throw new DurableObjectConfigError('sqlite must be a boolean', 'sqlite')\n  }\n\n  // Validate methods if provided\n  if (config.methods !== undefined) {\n    if (typeof config.methods !== 'object' || config.methods === null) {\n      throw new DurableObjectConfigError('methods must be an object', 'methods')\n    }\n\n    for (const methodName of Object.keys(config.methods)) {\n      // Check for reserved names\n      if (RESERVED_METHODS.has(methodName)) {\n        throw new DurableObjectConfigError(\n          `'${methodName}' is a reserved method name and cannot be used in methods config`,\n          'methods'\n        )\n      }\n\n      // Check that method is a function\n      if (typeof config.methods[methodName] !== 'function') {\n        throw new DurableObjectConfigError(\n          `methods.${methodName} must be a function`,\n          'methods'\n        )\n      }\n\n      // Validate method name format (must be valid JS identifier)\n      if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(methodName)) {\n        throw new DurableObjectConfigError(\n          `'${methodName}' is not a valid method name. Method names must be valid JavaScript identifiers`,\n          'methods'\n        )\n      }\n    }\n  }\n\n  // Validate handlers are functions\n  if (config.init !== undefined && typeof config.init !== 'function') {\n    throw new DurableObjectConfigError('init must be a function', 'init')\n  }\n\n  if (config.fetch !== undefined && typeof config.fetch !== 'function') {\n    throw new DurableObjectConfigError('fetch must be a function', 'fetch')\n  }\n\n  if (config.alarm !== undefined && typeof config.alarm !== 'function') {\n    throw new DurableObjectConfigError('alarm must be a function', 'alarm')\n  }\n\n  if (\n    config.webSocketMessage !== undefined &&\n    typeof config.webSocketMessage !== 'function'\n  ) {\n    throw new DurableObjectConfigError(\n      'webSocketMessage must be a function',\n      'webSocketMessage'\n    )\n  }\n\n  if (\n    config.webSocketClose !== undefined &&\n    typeof config.webSocketClose !== 'function'\n  ) {\n    throw new DurableObjectConfigError('webSocketClose must be a function', 'webSocketClose')\n  }\n\n  if (\n    config.webSocketError !== undefined &&\n    typeof config.webSocketError !== 'function'\n  ) {\n    throw new DurableObjectConfigError('webSocketError must be a function', 'webSocketError')\n  }\n}\n\n// ============================================================================\n// defineDurableObject()\n// ============================================================================\n\n/**\n * Define a Durable Object with native Cloudflare RPC support.\n *\n * This function creates a durable object definition that will be automatically\n * discovered and registered by Cloudwerk during build. The build process generates\n * a class extending Cloudflare's DurableObject with native RPC methods.\n *\n * @typeParam TState - The state type managed by this durable object\n * @typeParam TEnv - The environment bindings type\n * @param config - Durable object configuration\n * @returns Durable object definition\n *\n * @example\n * ```typescript\n * // app/objects/counter.ts\n * import { defineDurableObject } from '@cloudwerk/durable-object'\n *\n * interface CounterState {\n *   value: number\n * }\n *\n * export default defineDurableObject<CounterState>({\n *   sqlite: true,\n *\n *   async init(ctx) {\n *     ctx.sql.run(`CREATE TABLE IF NOT EXISTS logs (id INTEGER PRIMARY KEY, action TEXT)`)\n *     return { value: 0 }\n *   },\n *\n *   methods: {\n *     async increment(amount = 1) {\n *       this.state.value += amount\n *       this.ctx.sql.run(`INSERT INTO logs (action) VALUES ('increment')`)\n *       return this.state.value\n *     },\n *\n *     async getValue() {\n *       return this.state.value\n *     },\n *   },\n * })\n * ```\n *\n * @example\n * ```typescript\n * // Usage in route handler:\n * import { durableObjects } from '@cloudwerk/bindings'\n *\n * export async function POST(request: Request, { params }: Context) {\n *   const id = durableObjects.Counter.idFromName(params.id)\n *   const stub = durableObjects.Counter.get(id)\n *\n *   // Native RPC - direct method calls!\n *   const value = await stub.increment(5)\n *\n *   return Response.json({ value })\n * }\n * ```\n *\n * @example\n * ```typescript\n * // With HTTP fetch handler\n * import { defineDurableObject } from '@cloudwerk/durable-object'\n *\n * export default defineDurableObject<{ count: number }>({\n *   init: () => ({ count: 0 }),\n *\n *   async fetch(request) {\n *     const url = new URL(request.url)\n *\n *     if (url.pathname === '/increment') {\n *       this.state.count++\n *     }\n *\n *     return new Response(String(this.state.count))\n *   },\n * })\n * ```\n *\n * @example\n * ```typescript\n * // With WebSocket support\n * import { defineDurableObject } from '@cloudwerk/durable-object'\n *\n * interface ChatState {\n *   messages: string[]\n * }\n *\n * export default defineDurableObject<ChatState>({\n *   init: () => ({ messages: [] }),\n *\n *   async fetch(request) {\n *     const upgradeHeader = request.headers.get('Upgrade')\n *     if (upgradeHeader !== 'websocket') {\n *       return new Response('Expected WebSocket', { status: 426 })\n *     }\n *\n *     const pair = new WebSocketPair()\n *     this.ctx.acceptWebSocket(pair[1])\n *\n *     return new Response(null, { status: 101, webSocket: pair[0] })\n *   },\n *\n *   async webSocketMessage(ws, message) {\n *     this.state.messages.push(String(message))\n *\n *     // Broadcast to all connected clients\n *     for (const client of this.ctx.getWebSockets()) {\n *       client.send(String(message))\n *     }\n *   },\n * })\n * ```\n *\n * @example\n * ```typescript\n * // With alarm handler\n * import { defineDurableObject } from '@cloudwerk/durable-object'\n *\n * interface CleanupState {\n *   lastCleanup: number\n * }\n *\n * export default defineDurableObject<CleanupState>({\n *   async init(ctx) {\n *     // Schedule first alarm for 1 hour from now\n *     await ctx.storage.setAlarm(Date.now() + 60 * 60 * 1000)\n *     return { lastCleanup: Date.now() }\n *   },\n *\n *   async alarm() {\n *     // Perform periodic cleanup\n *     this.state.lastCleanup = Date.now()\n *\n *     // Reschedule for next hour\n *     await this.ctx.storage.setAlarm(Date.now() + 60 * 60 * 1000)\n *   },\n *\n *   methods: {\n *     getLastCleanup() {\n *       return this.state.lastCleanup\n *     },\n *   },\n * })\n * ```\n */\nexport function defineDurableObject<TState = unknown, TEnv = unknown>(\n  config: DurableObjectConfig<TState, TEnv>\n): DurableObjectDefinition<TState, TEnv> {\n  // Validate configuration\n  validateConfig(config)\n\n  // Create the definition object\n  const definition: DurableObjectDefinition<TState, TEnv> = {\n    __brand: 'cloudwerk-durable-object',\n    name: config.name,\n    sqlite: config.sqlite ?? false,\n    schema: config.schema,\n    config,\n  }\n\n  return definition\n}\n\n/**\n * Check if a value is a durable object definition created by defineDurableObject().\n *\n * @param value - Value to check\n * @returns true if value is a DurableObjectDefinition\n */\nexport function isDurableObjectDefinition(\n  value: unknown\n): value is DurableObjectDefinition {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '__brand' in value &&\n    (value as DurableObjectDefinition).__brand === 'cloudwerk-durable-object'\n  )\n}\n\n/**\n * Extract method names from a durable object definition.\n *\n * @param definition - The durable object definition\n * @returns Array of method names\n */\nexport function getMethodNames(definition: DurableObjectDefinition): string[] {\n  const methods = definition.config.methods\n  if (!methods) {\n    return []\n  }\n  return Object.keys(methods)\n}\n\n/**\n * Check if a durable object definition has any handlers.\n *\n * @param definition - The durable object definition\n * @returns true if at least one handler is defined\n */\nexport function hasHandlers(definition: DurableObjectDefinition): boolean {\n  const { config } = definition\n  return (\n    config.fetch !== undefined ||\n    config.alarm !== undefined ||\n    config.webSocketMessage !== undefined ||\n    (config.methods !== undefined && Object.keys(config.methods).length > 0)\n  )\n}\n\n/**\n * Check if a durable object definition has WebSocket support.\n *\n * @param definition - The durable object definition\n * @returns true if any WebSocket handler is defined\n */\nexport function hasWebSocketSupport(definition: DurableObjectDefinition): boolean {\n  const { config } = definition\n  return (\n    config.webSocketMessage !== undefined ||\n    config.webSocketClose !== undefined ||\n    config.webSocketError !== undefined\n  )\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cloudwerk/durable-object",
+  "version": "0.0.1",
+  "description": "Durable Objects support for Cloudwerk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/squirrelsoft-dev/cloudwerk.git",
+    "directory": "packages/durable-object"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@cloudwerk/core": "0.12.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241022.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.0.0",
+    "tsup": "^8.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0",
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest --run",
+    "test:watch": "vitest"
+  }
+}