errore 0.10.0 → 0.12.0

package/README.md

@@ -225,6 +225,8 @@ if (result instanceof Error) {
 The error definitions:
 
 ```ts
+import * as errore from 'errore'
+
 class NotFoundError extends errore.createTaggedError({
   name: 'NotFoundError',
   message: 'User $id not found'
@@ -299,6 +301,8 @@ Returns `undefined` if no matching ancestor is found. Safe against circular `.ca
 Use `extends` to inherit from a custom base class. The error will pass `instanceof` for both the base class and the specific error class:
 
 ```ts
+import * as errore from 'errore'
+
 class AppError extends Error {
   statusCode = 500
   toResponse() { return { error: this.message, code: this.statusCode } }
@@ -361,6 +365,11 @@ const response = await errore.tryAsync({
 })
 ```
 
+> **Best practices for `try` / `tryAsync`:**
+> - **Use as low as possible in the call stack** — only at boundaries with uncontrolled dependencies (third-party libs, `JSON.parse`, `fetch`, file I/O). Your own functions should return errors as values, never throw.
+> - **Keep the callback minimal** — wrap only the single throwing call, not your business logic. The `try` callback should be a one-liner.
+> - **Always prefer `errore.try` over `errore.tryFn`** — they are the same function, but `try` is the canonical name.
+
 ### Transformations
 
 **Transform and chain** operations:
@@ -381,6 +390,54 @@ const posts = errore.andThen(user, u => fetchPosts(u.id))
 const logged = errore.tap(user, u => console.log('Got user:', u.name))
 ```
 
+### Resource Cleanup (defer)
+
+errore ships `DisposableStack` and `AsyncDisposableStack` polyfills for Go-like `defer` cleanup. Works in every runtime — no native `DisposableStack` support needed:
+
+```ts
+import * as errore from 'errore'
+
+async function processRequest(id: string): Promise<DbError | Result> {
+  // await using = cleanup runs automatically when scope exits
+  await using cleanup = new errore.AsyncDisposableStack()
+
+  const db = await connectDb()
+  cleanup.defer(() => db.close())
+
+  const cache = await openCache()
+  cleanup.defer(() => cache.flush())
+
+  // ... use db and cache ...
+  return result
+  // cleanup runs in LIFO order: cache.flush() → db.close()
+}
+```
+
+Resources are released in **reverse order** (last deferred = first cleaned up), just like Go's `defer`. Cleanup runs on normal return, early error return, or thrown exception.
+
+```ts
+// Sync version with using
+function readConfig(path: string): ParseError | Config {
+  using cleanup = new errore.DisposableStack()
+
+  const file = openFileSync(path)
+  cleanup.defer(() => file.closeSync())
+
+  const lock = acquireLock(path)
+  cleanup.defer(() => lock.release())
+
+  return parseConfig(file.readSync())
+}
+```
+
+You can also register existing `Disposable` objects directly:
+
+```ts
+await using cleanup = new errore.AsyncDisposableStack()
+cleanup.use(dbConnection)   // calls dbConnection[Symbol.dispose]() on exit
+cleanup.adopt(handle, (h) => h.close())  // custom cleanup for non-disposable values
+```
+
 ### Extraction
 
 **Extract values** or throw, **split arrays** by success/error:
@@ -675,6 +732,8 @@ Effect is powerful if you need its full feature set. But if you just want type-s
 | Learning curve | Steep (new paradigm) | Minimal (just `instanceof`) |
 | Codebase impact | Pervasive (everything becomes an Effect) | Surgical (adopt incrementally) |
 | Bundle size | ~50KB+ | **~0 bytes** |
+| Resource cleanup | `Scope` + `addFinalizer` + `acquireRelease` | `using` + `DisposableStack.defer()` |
+| Cancellation | Fiber interruption model | Native `AbortController` |
 | Use case | Full FP framework | Just error handling |
 
 **Use Effect** when you want dependency injection, structured concurrency, and the full functional programming experience.