Simplifies usage of Cloudflare Durable Objects, allowing lightweight object definitions and direct access to object methods from within Workers (no need for request building/handling).
- Removes nearly all boilerplate from writing and using Durable Objects.
- Optional automatic non-blocking persistance layer
- Optionally return contents from methods without explicit return (convenience feature)
- Control how contents of object looks to outside requests
- Control exactly what, if anything, is persisted
- Already being used in production on high-availability/throughput apps like the Retheme browser extension!
npm install itty-router itty-durable
import { createDurable } from 'itty-durable'
export class Counter extends createDurable({ autoReturn: true }) {
constructor(state, env) {
super(state, env)
// anything defined here is only used for initialization (if not loaded from storage)
this.counter = 0
}
// Because this function does not return anything, it will return the entire contents
// Example: { counter: 1 }
increment() {
this.counter++
}
// Any explicit return will honored, despite the autoReturn flag.
// Note that any serializable params can passed through from the Worker without issue.
add(a, b) {
return a + b
}
}import { ThrowableRouter, missing, withParams } from 'itty-router-extras'
import { withDurables } from 'itty-durable'
// export the durable class, per spec
export { Counter } from './Counter'
const router = ThrowableRouter({ base: '/counter' })
router
// add upstream middleware, allowing Durable access off the request
.all('*', withDurables())
// get the durable itself... returns json response, so no need to wrap
.get('/', ({ Counter }) => Counter.get('test').toJSON())
// By using { autoReturn: true } in createDurable(), this method returns the contents
.get('/increment', ({ Counter }) => Counter.get('test').increment())
// you can pass any serializable params to a method... (e.g. /counter/add/3/4 => 7)
.get('/add/:a?/:b?', withParams,
({ Counter, a, b }) => Counter.get('test').add(Number(a), Number(b))
)
// reset the durable
.get('/reset', ({ Counter }) => Counter.get('test').reset())
// 404 for everything else
.all('*', () => missing('Are you sure about that?'))
// with itty, and using ES6 module syntax (required for DO), this is all you need
export default {
fetch: router.handle
}
/*
Example Interactions:
GET /counter => { counter: 0 }
GET /counter/increment => { counter: 1 }
GET /counter/increment => { counter: 2 }
GET /counter/increment => { counter: 3 }
GET /counter/reset => { counter: 0 }
GET /counter/add/20/3 => 23
*/This library works via a two part process:
-
First of all, we create a base class for your Durable Objects to extend (through
createDurable()). This embeds the persistance layer, a few convenience functions, and most importantly, a tiny internal itty-router to handle fetch requests. Using this removes the boilerplate from your objects themselves, allowing them to be only business logic. -
Next, we expose the
withDurables()middleware for use within your Workers (it is designed for drop-in use with itty-router, but should work with virtually any typical Worker router). This embeds proxied stubs (translation: "magic stubs") into the Request. Using these stubs, you can call methods on the Durable Object directly, rather than manually creating fetch requests to do so (that's all handled internally, communicating with the embedded router within the Durable Objects themselves).
npm install itty-durable
Factory function to create the IttyDurable class (with options) for your Durable Object to extend.
| Option | Type(s) | Default | Description |
|---|---|---|---|
| autoPersist | boolean |
false | By default, all contents are stored in-memory only, and are cleared when the DO evacuates from memory (unless explicitly asked to persist). By setting this to true, each request to the DO through the stub will persist the contents automatically. |
| autoReturn | boolean |
false | If set to true, methods without an explicit return will return the contents of the object itself (as controlled through the toJSON() method). This method is overridable for custom payload shaping. |
Highly-recommended middleware to embed itty-durable stubs into the request. Using these stubs allows you to skip manually creating/sending requests or handling response parsing.
| Option | Type(s) | Default | Description |
|---|---|---|---|
| parse | boolean |
false | By default, the stub methods return a Promise to the Response from the Durable Object itself. This is great if you're just passing the response along and don't want to modify it. To take more control, setting this to true will instead return a Promise to the parsed JSON contents instead. To then respond to requests, you would have to handle building of a JSON Response yourself (e.g. json() within itty-router-extras). |
Big time thanks to all the fantastic developers on the Cloudflare Workers discord group, for their putting up with my constant questions, code snippets, and guiding me off the dangerous[ly flawed] path of async setters ;)
Let's face it, in open source, these are the real heroes... improving the quality of libraries out there for everyone!
- README tweaks, fixes, improvements: @tomByrer