@lunora/queue 1.0.0-alpha.1 → 1.0.0-alpha.100

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -26,18 +26,36 @@ import { api } from "./_generated/api";
 export const emailQueue = defineQueue<{ to: string }>({
     handler: async (ctx, batch) => {
         for (const message of batch.messages) {
-            await ctx.run(api.email.send, { to: message.body.to });
+            await message.run(api.email.send, { to: message.body.to });
             message.ack();
         }
     },
 });
 ```
 
+`message.run(...)` is `ctx.run(...)` pinned to that message. Call it inside the
+batch loop: when the dispatched function fails deterministically (`400`, `403`,
+`404`, `422`), the consumer acks just that message and retries the rest instead
+of letting one poison message retry — and eventually dead-letter — the whole
+batch.
+
 ```ts
 // inside a mutation/action
 await ctx.queues.emailQueue.send({ to: user.email });
 ```
 
+For one event with several consumers, declare a topic and subscribe to it.
+Each subscription is its own queue, with its own retries and dead-letter queue:
+
+```ts
+// lunora/queues.ts
+export const signups = defineTopic<{ userId: string }>();
+export const welcomeEmail = defineSubscription(signups, { handler: async (ctx, batch) => {} });
+
+// inside a mutation/action
+await ctx.topics.signups.publish({ userId });
+```
+
 Codegen emits the typed `ctx.queues` producer and the worker `queue()` dispatch;
 `@lunora/config` reconciles the wrangler `queues.producers[]` /
 `queues.consumers[]` entries from the same definition. Scaffold a new queue with