@valentinkolb/sync 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Set version from tag
+        run: npm version ${GITHUB_REF#refs/tags/v} --no-git-tag-version
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build package
+        run: bun build ./index.ts --outdir ./dist --target node
+
+      - name: Create dist package.json
+        run: |
+          # Get version from package.json
+          VERSION=$(node -p "require('./package.json').version")
+
+          # Create package.json for dist with lowercase name for npm
+          cat > dist/package.json << EOF
+          {
+            "name": "@valentinkolb/sync",
+            "version": "$VERSION",
+            "description": "Distributed synchronization primitives for Bun and TypeScript",
+            "main": "index.js",
+            "module": "index.js",
+            "types": "index.d.ts",
+            "type": "module",
+            "exports": {
+              ".": {
+                "import": "./index.js",
+                "types": "./index.d.ts"
+              }
+            },
+            "peerDependencies": {
+              "zod": "^3"
+            },
+            "keywords": ["bun", "redis", "ratelimit", "mutex", "jobs", "queue", "distributed"],
+            "author": "Valentin Kolb",
+            "license": "MIT",
+            "repository": {
+              "type": "git",
+              "url": "git+https://github.com/ValentinKolb/sync.git"
+            }
+          }
+          EOF
+
+      - name: Generate type declarations
+        run: bunx tsc --declaration --emitDeclarationOnly --outDir dist
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        working-directory: ./dist

package/CLAUDE.md

@@ -0,0 +1,106 @@
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+
+// import .css files directly and it works
+import './index.css';
+
+import { createRoot } from "react-dom/client";
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentin Kolb
+
+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/README.md

@@ -0,0 +1,292 @@
+# @valentinkolb/sync
+
+Distributed synchronization primitives for Bun and TypeScript. Built on Redis for horizontal scaling.
+
+**Zero external dependencies** - uses only Bun's native Redis client (`Bun.redis`) and Zod for schema validation.
+
+## Features
+
+- **Rate Limiting** - Sliding window algorithm for smooth rate limiting
+- **Distributed Mutex** - Acquire locks across multiple processes with automatic expiry
+- **Background Jobs** - Delayed, scheduled, and periodic jobs with retries
+- **Horizontal Scaling** - All state in Redis, run multiple instances safely
+- **Type Safe** - Full TypeScript support with Zod schema validation for jobs
+
+## Installation
+
+```bash
+bun add @valentinkolb/sync zod
+```
+
+## Quick Start
+
+### Rate Limiting
+
+```typescript
+import { ratelimit } from "@valentinkolb/sync";
+
+const limiter = ratelimit.create({
+  limit: 100,      // 100 requests
+  windowSecs: 60,  // per minute
+});
+
+const result = await limiter.check("user:123");
+if (result.limited) {
+  console.log(`Rate limited. Retry in ${result.resetIn}ms`);
+}
+
+// Or throw on limit
+await limiter.checkOrThrow("user:123");
+```
+
+### Distributed Mutex
+
+```typescript
+import { mutex } from "@valentinkolb/sync";
+
+const m = mutex.create();
+
+// Automatic acquire/release
+const result = await m.withLock("resource:123", async () => {
+  // Only one process can execute this at a time
+  return await doExclusiveWork();
+});
+
+// Or throw if lock cannot be acquired
+const result = await m.withLockOrThrow("resource:123", async () => {
+  return await doExclusiveWork();
+});
+```
+
+### Background Jobs
+
+```typescript
+import { jobs } from "@valentinkolb/sync";
+import { z } from "zod";
+
+// Create a typed job queue
+const emailJobs = jobs.create({
+  name: "emails",
+  schema: z.object({
+    to: z.string().email(),
+    subject: z.string(),
+    body: z.string(),
+  }),
+});
+
+// Send jobs
+await emailJobs.send({ to: "user@example.com", subject: "Hello", body: "World" });
+
+// Process jobs
+const stop = emailJobs.process(async (job) => {
+  await sendEmail(job.data);
+}, { concurrency: 10 });
+```
+
+## Rate Limiting
+
+Uses a sliding window algorithm that provides smoother rate limiting than fixed windows.
+
+```typescript
+import { ratelimit, RateLimitError } from "@valentinkolb/sync";
+
+const limiter = ratelimit.create({
+  limit: 100,        // Max requests in window
+  windowSecs: 60,    // Window size in seconds (default: 1)
+  prefix: "rl",      // Redis key prefix (default: "ratelimit")
+});
+
+// Check without throwing
+const result = await limiter.check("user:123");
+// { limited: boolean, remaining: number, resetIn: number }
+
+// Check and throw RateLimitError if limited
+try {
+  await limiter.checkOrThrow("user:123");
+} catch (e) {
+  if (e instanceof RateLimitError) {
+    console.log(`Retry in ${e.resetIn}ms`);
+  }
+}
+```
+
+## Distributed Mutex
+
+Uses Redis SET NX for atomic lock acquisition with automatic expiry to prevent deadlocks.
+
+```typescript
+import { mutex, LockError } from "@valentinkolb/sync";
+
+const m = mutex.create({
+  prefix: "lock",       // Redis key prefix (default: "mutex")
+  retryCount: 10,       // Retry attempts (default: 10)
+  retryDelay: 200,      // Delay between retries in ms (default: 200)
+  defaultTtl: 10000,    // Lock TTL in ms (default: 10000)
+});
+
+// Automatic release with withLock
+const result = await m.withLock("resource", async (lock) => {
+  // Extend lock if operation takes longer than expected
+  await m.extend(lock, 30000);
+  return await longOperation();
+});
+
+// Returns null if lock cannot be acquired
+if (result === null) {
+  console.log("Could not acquire lock");
+}
+
+// Or throw LockError
+try {
+  await m.withLockOrThrow("resource", async () => {
+    return await doWork();
+  });
+} catch (e) {
+  if (e instanceof LockError) {
+    console.log(`Failed to lock: ${e.resource}`);
+  }
+}
+
+// Manual acquire/release
+const lock = await m.acquire("resource");
+if (lock) {
+  try {
+    await doWork();
+  } finally {
+    await m.release(lock);
+  }
+}
+```
+
+## Background Jobs
+
+A Redis-backed job queue with support for delayed jobs, periodic scheduling, retries, and timeouts.
+
+### Creating a Queue
+
+```typescript
+import { jobs } from "@valentinkolb/sync";
+import { z } from "zod";
+
+const emailJobs = jobs.create({
+  name: "emails",                        // Queue name
+  schema: z.object({                     // Zod schema for validation
+    to: z.string().email(),
+    subject: z.string(),
+    body: z.string(),
+  }),
+  prefix: "jobs",                        // Redis key prefix (default: "jobs")
+});
+```
+
+### Sending Jobs
+
+```typescript
+// Immediate execution
+await emailJobs.send({ to: "...", subject: "...", body: "..." });
+
+// Delayed execution
+await emailJobs.send(data, { delay: 5000 });        // In 5 seconds
+await emailJobs.send(data, { at: Date.now() + 60000 }); // At specific time
+
+// Periodic jobs
+await emailJobs.send(data, { interval: 3600000 });  // Every hour
+await emailJobs.send(data, { interval: 3600000, startImmediately: true });
+
+// With retries and timeout
+await emailJobs.send(data, {
+  retries: 3,       // 1 initial + 3 retries = 4 attempts
+  timeout: 60000,   // Fail if processing takes > 60s
+});
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `delay` | Delay execution by ms | - |
+| `at` | Execute at timestamp | - |
+| `interval` | Repeat every ms | - |
+| `startImmediately` | Start interval job immediately | `false` |
+| `retries` | Number of retries on failure | `0` |
+| `timeout` | Max processing time before hard fail | `30000` |
+
+> **Note:** `delay`, `at`, and `interval` are mutually exclusive.
+
+### Processing Jobs
+
+```typescript
+const stop = emailJobs.process(async (job) => {
+  console.log(`Processing job ${job.id}`);
+  await sendEmail(job.data);
+}, {
+  concurrency: 10,      // Process 10 jobs in parallel
+  pollInterval: 1000,   // Poll every 1s when queue is empty
+  
+  onSuccess: (job) => {
+    console.log(`Job ${job.id} completed`);
+  },
+  
+  onError: (job, error) => {
+    // Called when job permanently fails or interval job fails
+    console.error(`Job ${job.id} failed:`, error.message);
+  },
+  
+  onFinally: (job) => {
+    // Called after every attempt (success or failure)
+    console.log(`Job ${job.id} attempt finished`);
+  },
+});
+
+// Stop processing
+stop();
+```
+
+### Job Object
+
+```typescript
+type Job<T> = {
+  id: string;
+  data: T;
+  status: "waiting" | "delayed" | "active" | "completed" | "failed";
+  attempts: number;
+  maxRetries: number;
+  timeout: number;
+  interval?: number;
+  createdAt: number;
+  scheduledAt?: number;
+  startedAt?: number;
+  completedAt?: number;
+  error?: string;
+};
+```
+
+### Horizontal Scaling
+
+Jobs are safe to process across multiple instances. Each job is claimed atomically using Redis RPOPLPUSH, ensuring exactly-once processing.
+
+```
+                    ┌─────────────┐
+                    │   Redis     │
+                    │  (waiting)  │
+                    └──────┬──────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         │                 │                 │
+         ▼                 ▼                 ▼
+    ┌─────────┐       ┌─────────┐       ┌─────────┐
+    │ Worker  │       │ Worker  │       │ Worker  │
+    │ (Pod 1) │       │ (Pod 2) │       │ (Pod 3) │
+    └─────────┘       └─────────┘       └─────────┘
+```
+
+## Configuration
+
+The library reads Redis connection from environment variables:
+
+| Variable | Default |
+|----------|---------|
+| `REDIS_URL` | `redis://localhost:6379` |
+| `VALKEY_URL` | (fallback) |
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,29 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "sync",
+      "devDependencies": {
+        "@types/bun": "latest",
+        "zod": "^3.24.0",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+        "zod": "^3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.8", "", { "dependencies": { "bun-types": "1.3.8" } }, "sha512-3LvWJ2q5GerAXYxO2mffLTqOzEu5qnhEAlh48Vnu8WQfnmSwbgagjGZV6BoHKJztENYEDn6QmVd949W4uESRJA=="],
+
+    "@types/node": ["@types/node@25.1.0", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-t7frlewr6+cbx+9Ohpl0NOTKXZNV9xHRmNOvql47BFJKcEG1CxtxlPEEe+gR9uhVWM4DwhnvTF110mIL4yP9RA=="],
+
+    "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
+    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+  }
+}

package/compose.test.yml

@@ -0,0 +1,7 @@
+services:
+  valkey:
+    image: docker.io/valkey/valkey:8-alpine
+    container_name: sync_test_valkey
+    command: valkey-server --save "" --appendonly no
+    ports:
+      - "6399:6379"

package/index.ts

@@ -0,0 +1,18 @@
+export {
+  ratelimit,
+  RateLimitError,
+  type RateLimiter,
+  type RateLimitResult,
+  type RateLimitConfig,
+} from "./src/ratelimit";
+export { mutex, LockError, type Mutex, type Lock, type MutexConfig } from "./src/mutex";
+export {
+  jobs,
+  JobsError,
+  ValidationError,
+  type Jobs,
+  type Job,
+  type JobsConfig,
+  type SendOptions,
+  type ProcessOptions,
+} from "./src/jobs";

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@valentinkolb/sync",
+  "version": "0.1.0",
+  "description": "General purpose sync primitives for TypeScript and Bun (ratelimit, mutex, jobs)",
+  "module": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "scripts": {
+    "test": "bun test --preload ./tests/preload.ts"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "zod": "^3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "zod": "^3.24.0"
+  }
+}