@oncely/express 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stacks0x
+
+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

@@ -1,48 +1,103 @@
 # @oncely/express
 
-Express middleware for oncely idempotency.
+Express middleware for HTTP idempotency.
+
+[![npm version](https://img.shields.io/npm/v/@oncely/express.svg)](https://www.npmjs.com/package/@oncely/express)
 
 ## Installation
 
+```bash
 npm install @oncely/core @oncely/express
+```
 
-## Usage
+## Quick Start
 
+```typescript
 import express from 'express';
-import { express as idempotent, configure } from '@oncely/express';
+import { express as idempotent } from '@oncely/express';
 
 const app = express();
+app.use(express.json());
 
-// Zero-config (uses memory storage)
+// Zero-config: memory storage, 24h TTL
 app.post('/orders', idempotent(), async (req, res) => {
-res.status(201).json(await createOrder(req.body));
+  const order = await createOrder(req.body);
+  res.status(201).json(order);
 });
-
-// With options
-app.post('/payments', idempotent({
-required: true,
-ttl: '1h',
-}), paymentHandler);
-
-// Pre-configured factory
+```
+
+## Configuration
+
+```typescript
+app.post(
+  '/payments',
+  idempotent({
+    storage: redis(), // Storage adapter
+    ttl: '1h', // Cache duration
+    required: true, // Require Idempotency-Key header
+    methods: ['POST', 'PUT'], // HTTP methods to protect
+    failOpen: true, // Continue if storage fails
+    getKey: (req) => req.headers['x-request-id'], // Custom key extraction
+    getHash: (req) => hashObject(req.body), // Custom hash function
+    onHit: (key, response) => {}, // Cache hit callback
+    onMiss: (key) => {}, // Cache miss callback
+    onError: (key, error) => {}, // Error callback
+  }),
+  handler
+);
+```
+
+## Pre-configured Factory
+
+Share configuration across routes:
+
+```typescript
+import { configure } from '@oncely/express';
 import { redis } from '@oncely/redis';
 
 const idempotent = configure({
-storage: redis(),
-ttl: '1h',
+  storage: redis(),
+  ttl: '1h',
 });
 
 app.post('/orders', idempotent(), orderHandler);
 app.post('/payments', idempotent({ required: true }), paymentHandler);
+```
 
 ## Headers
 
-Request: Idempotency-Key
-Response: Idempotency-Key, Idempotency-Replay (on cache hit)
+| Header               | Direction | Description                           |
+| -------------------- | --------- | ------------------------------------- |
+| `Idempotency-Key`    | Request   | Client-provided unique key            |
+| `Idempotency-Key`    | Response  | Echo of the key used                  |
+| `Idempotency-Replay` | Response  | `true` when returning cached response |
 
-## License
+## Error Responses
 
-MIT
+All errors follow [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807):
+
+| Status | Type           | Cause                               |
+| ------ | -------------- | ----------------------------------- |
+| 400    | `key-required` | Missing key when `required: true`   |
+| 409    | `conflict`     | Request with same key in progress   |
+| 422    | `mismatch`     | Same key reused with different body |
+
+```json
+{
+  "type": "https://oncely.dev/errors/conflict",
+  "title": "Conflict",
+  "status": 409,
+  "detail": "A request with this idempotency key is already being processed"
+}
+```
+
+## With Redis
+
+```typescript
+import { redis } from '@oncely/redis';
+
+app.post('/orders', idempotent({ storage: redis() }), handler);
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oncely/express",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Express middleware for oncely idempotency",
   "author": "stacks0x",
   "license": "MIT",
@@ -31,27 +31,27 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
-    "@oncely/core": "workspace:*",
-    "express": "^4.18.0 || ^5.0.0"
+    "express": "^4.18.0 || ^5.0.0",
+    "@oncely/core": "0.2.2"
   },
   "devDependencies": {
-    "@oncely/core": "workspace:*",
     "@types/express": "^5.0.6",
     "express": "^5.2.1",
     "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "@oncely/core": "0.2.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
   }
-}
+}