Release v1.0.10 — "hungry_maxwell" 🚀🍽️

A tasty little release focused on developer ergonomics, clearer worker/client handling, improved documentation for Client↔Server integration, and a few internal refactors to make TypeScript friendliness and tracing more reliable.

Highlights

✨ New: Client-Server Integration docs + Next.js & Bun guidance
♻️ Refactor: Task handler signatures become destructured objects (breaking change)
🐒 Refactor: MonkeyCapture decorator now uses workerId (breaking change)
🛠️ Improvement: Worker class better handles job data and retains instance id
⚙️ CI: auto-release workflow ignores doc/markdown changes
📝 Changelog updated to 1.0.9 -> 1.0.10 and release notes generator model bumped

Features ✨
Refactors & Improvements ♻️
Bugfixes & Chores 🧹
Breaking Changes & Migration Steps ⚠️
Code Examples & Snippets 🧩
Architecture Diagrams (Mermaid) 🗺️
Deployment Notes & CI Updates 🚀
Performance Impact 📈
New Dependencies 📦
API Compatibility & Backwards Compatibility 🔁
Security Advisory 🔒
Contributors & Acknowledgements 🙏

Features ✨

docs: Added a dedicated "Client-Server Integration" section in docs configuration. This includes recipes for Next.js and Bun showing how to connect a browser/client to the worker-based backend and how to route tasks, including code samples and recommended patterns.
workflow: Updated auto-release workflow to add paths-ignore so documentation and markdown-only changes don’t trigger releases. This reduces noisy releases from doc-only changes.

Refactors & Improvements ♻️

refactor: enhanced task handler signatures and worker/client instance handling
- Task handler signatures were changed to accept a single destructured object for clarity and extensibility. This improves readability and helps with optional params.
- Worker and client instance retrieval code updated to use as any in TypeScript to avoid strict typing issues at runtime while preserving behavior.
- Email and payment service methods were refactored to align with the new parameter structure (destructured objects).
refactor: MonkeyCapture decorator and Worker class
- The MonkeyCapture decorator now expects workerId (renamed from instanceId) for clarity.
- Task history key generation is updated to use workerId.
- The Worker class now stores instanceId and ensures it is passed properly to MonkeyCapture.
- Worker job data extraction logic improved to better handle nested or optional job data payloads.
chore: updated the model string in the release notes generator from claude-3.5-sonnet → gpt-5-mini (dev tooling only).

Bugfixes & Chores 🧹

docs and changelog reorganized for better clarity and to reflect the Client-Server architecture changes.
Updated changelog to reflect 1.0.9 and improvements leading to 1.0.10.

Breaking Changes & Migration Steps ⚠️

There are two notable breaking changes you must adopt:

Task handler signature change

Old signature (positional arguments):

// OLD
async function handleTask(jobId: string, payload: any) {
  // ...
}

New signature (destructured object):

// NEW
async function handleTask({ jobId, payload }: { jobId: string; payload: any }) {
  // ...
}

Migration steps:

Update all task handler definitions to accept a single parameter object and destructure it.

Update any places that call handlers directly (tests, local invocations) to pass an object:

// OLD
handleTask("id-123", { foo: "bar" });

// NEW
handleTask({ jobId: "id-123", payload: { foo: "bar" } });

MonkeyCapture: instanceId → workerId

Decorator rename and task history key usage updated.

Old usage:

// OLD
@MonkeyCapture({ instanceId: 'abc123' })
class MyWorker { /* ... */ }

New usage:
```
// NEW
@MonkeyCapture({ workerId: 'abc123' })
class MyWorker { /* ... */ }
```
Migration steps:
- Replace all instanceId decorator option usages with workerId.
- Ensure Worker instances supply instanceId (internal field) so the decorator receives workerId at runtime. The library now maps the internal instanceId to the decorator's workerId automatically, but ensure any direct references are updated.

TypeScript notes:

The codebase now uses as any in a few places for client/worker instance retrieval to ease compatibility. If you depend on strict typing, update local types or add assertion helpers:
```
const worker = getWorkerInstance() as any; // library side
// Your side, prefer:
const worker = getWorkerInstance() as WorkerInstance;
```

Code Examples & Snippets 🧩

Example: New task handler signature and registration

// handler.ts
export async function sendWelcomeEmail({
  jobId,
  payload,
  meta
}: {
  jobId: string;
  payload: { email: string; name?: string };
  meta?: Record<string, any>;
}) {
  // clear, destructured parameters
  await emailService.send({ to: payload.email, name: payload.name });
  // ...
}

// registration
taskManager.register("sendWelcomeEmail", sendWelcomeEmail);

Example: MonkeyCapture decorator (new form)

// capture.ts
function MonkeyCapture(options: { workerId?: string }) {
  return function (target: any) {
    // decorator logic that now relies on options.workerId
    // task history keys are generated with workerId
  };
}

// usage
@MonkeyCapture({ workerId: "worker-42" })
class Worker { /* ... */ }

Example: Worker storing instanceId and passing to MonkeyCapture

class Worker {
  private instanceId: string;

  constructor(instanceId?: string) {
    this.instanceId = instanceId ?? generateId();
    // ensure decorator receives workerId
  }

  handle(job: any) {
    const data = this.extractJobData(job);
    // ...
  }

  private extractJobData(job: any) {
    // improved handling: supports nested job.data, optional fields
    return job?.data ?? job;
  }
}

Docs: Client-Server Integration snippet (Next.js)

// pages/api/task.ts (Next.js API route)
import { createClient } from 'cleo-client';

export default async function handler(req, res) {
  const client = createClient({ url: process.env.CLEO_SERVER_URL });
  const response = await client.enqueueTask({ type: 'generate-report', payload: req.body });
  res.status(200).json(response);
}

Architecture Diagrams (Mermaid) 🗺️

Client ↔ Server workflow (high-level)

flowchart LR
  A[Browser Client] -->|HTTP/WS| B[Next.js / Bun App]
  B -->|enqueueTask| C[Cleo Client]
  C -->|RPC/HTTP| D[Cleo Server / Worker Router]
  D --> E[Worker Instances]
  E -->|MonkeyCapture| F[Task History / Tracing]
  E -->|calls| G[EmailService, PaymentService, Other Integrations]

Worker lifecycle & data flow

sequenceDiagram
  participant Client
  participant Server
  participant Worker
  participant HistoryDB

  Client->>Server: enqueueTask({ type, payload })
  Server->>Worker: dispatchJob(job)
  Worker->>Worker: extractJobData(job)
  Worker->>HistoryDB: MonkeyCapture.store(jobId, workerId, status)
  Worker->>Worker: processPayload(payload)
  Worker->>HistoryDB: MonkeyCapture.update(jobId, workerId, result)
  Worker-->>Server: jobResult
  Server-->>Client: response

Deployment Notes & CI Updates 🚀

The auto-release workflow now has paths-ignore for doc and markdown files. If you maintain release automation, ensure your workflow expectations match (docs-only commits will no longer trigger releases).
No runtime server changes required for deployment beyond standard build and restart.
Recommended deployment steps:
1. Pull v1.0.10 tag/release
2. Update any code that relied on old task handler signatures or MonkeyCapture options
3. Build and run tests: pnpm install && pnpm build && pnpm test (or your preferred workflow)
4. Deploy as usual (restart server/scale workers)
5. Monitor task traces and logs to validate workerId keys are recorded properly

Performance Impact 📈

Dev-tooling change (release notes generator model) may improve release-note generation performance and quality (gpt-5-mini).
Runtime perf: No significant performance regressions expected. The changes to data extraction in Worker should reduce errors and may slightly reduce task processing latency for malformed payloads.
Type-casting to as any has no runtime performance impact—only affects TypeScript compile-time checking.

New Dependencies 📦

No new runtime dependencies were introduced in v1.0.10.
Dev change: release notes generator model string updated (development tool config only).

If you have a dependency graph checker in CI, no runtime package updates are required for this release.

API Changes & Backwards Compatibility 🔁

Task handler API changed from positional args to a single destructured object. This is a breaking change — see migration steps above.
MonkeyCapture decorator options rename: instanceId → workerId. This is breaking if you used the old option key.
Worker class stores instanceId internally now and maps it to the decorator's workerId. If code depended on internal properties, audit for naming changes.
Other public APIs remain compatible. Email and Payment services have been refactored to accept destructured params; calls should be updated accordingly (examples above).

Security Advisory 🔒

There are no identified security vulnerabilities in this release.
Note: We introduced a few as any type casts to smooth TypeScript interop. While harmless at runtime, they reduce type-safety guarantees. We recommend:
- Auditing any places that rely on precise runtime types
- Adding additional runtime guard checks where user/third-party input is consumed
As always, ensure environment variables and secret keys (email/payment) are stored securely and not logged.

Contributors & Acknowledgements 🙏

Thank you to the maintainers and contributors for this release!
Maintainers: theboringhumane (repository owner) and project contributors
Special thanks for documentation updates and CI improvements 🎉

If you contributed code or docs and are not listed here, please open a PR to add your contribution attribution.

Changelog Notes

This release builds on 1.0.9 changes (auto-release, client-server docs) and introduces internal refactors and signature changes aimed at better ergonomics and clearer tracing.
Version bumped to 1.0.10 — codename: hungry_maxwell.

If you need a migration helper script or PR diff examples to bulk-update handlers and decorator usages across your codebase, reply and I can generate that for you. 🛠️🐒

Navigation Menu

Repository navigation

hungry_maxwell

Choose a tag to compare

Sorry, something went wrong.