@freecorps/ember-rate-limit 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeCorps
+
+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,3 +1,12 @@
-# Temporary Holding Version
+# @freecorps/ember-rate-limit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rate limiting component for Ember: token bucket and fixed window per key, stored in the shard and transactional inside mutations; optional Cloudflare Rate Limiting binding helper.
+
+Part of [Ember](https://github.com/freecorps/ember), a Convex-style backend on Cloudflare Workers and Durable
+Objects. Source: [`packages/rate-limit`](https://github.com/freecorps/ember/tree/main/packages/rate-limit).
+
+```sh
+npm install @freecorps/ember-rate-limit
+```
+
+License: MIT.

package/dist/algorithms.d.ts

@@ -0,0 +1,54 @@
+export type TokenBucket = {
+    kind: "token bucket";
+    rate: number;
+    period: number;
+    capacity?: number;
+    maxReserved?: number;
+};
+export type FixedWindow = {
+    kind: "fixed window";
+    rate: number;
+    period: number;
+    capacity?: number;
+    start?: number;
+    maxReserved?: number;
+};
+export type RateLimitConfig = TokenBucket | FixedWindow;
+/** Stored per (name, key): tokens left and the time they were computed for (window start for fixed windows). */
+export type RateLimitState = {
+    value: number;
+    ts: number;
+};
+export type RateLimitResult = {
+    ok: true;
+    retryAfter?: undefined;
+}
+/** `retryAfter`: ms until `count` tokens are available (or, with `reserve`, until the reservation is valid). */
+ | {
+    ok: false;
+    retryAfter: number;
+};
+export type ReserveResult = {
+    ok: true;
+    retryAfter?: number;
+} | {
+    ok: false;
+    retryAfter: number;
+};
+export declare const SECOND = 1000;
+export declare const MINUTE: number;
+export declare const HOUR: number;
+export declare const DAY: number;
+export declare function checkConfig(c: RateLimitConfig): void;
+/** The state as of `now` (refilled), without consuming anything. `prev` null = never used: a full bucket. */
+export declare function refill(c: RateLimitConfig, prev: RateLimitState | null, now: number): RateLimitState;
+/**
+ * Consumes `count` tokens if available. Returns the decision and the state to store (unchanged on refusal:
+ * a refused call costs nothing).
+ */
+export declare function consume(c: RateLimitConfig, prev: RateLimitState | null, now: number, count?: number, reserve?: boolean): {
+    result: ReserveResult;
+    state: RateLimitState | null;
+};
+/** Whether `count` tokens are available now, without consuming them. */
+export declare function check(c: RateLimitConfig, prev: RateLimitState | null, now: number, count?: number): RateLimitResult;

package/dist/algorithms.js

@@ -0,0 +1,88 @@
+// Pure rate-limit math (no I/O, no clock): the component's mutation feeds it the stored state and `ctx.now`.
+//
+// - Token bucket: `capacity` tokens (default `rate`), refilled continuously at `rate` per `period` ms. Bursts up
+//   to `capacity`, then a steady `rate / period`.
+// - Fixed window: `rate` tokens are added at the start of every window of `period` ms (windows aligned to
+//   `start`, default 0 = the epoch), up to `capacity` (default `rate`: unused tokens do not carry over).
+//
+// `reserve: true` takes the tokens even when there are not enough (the value goes negative) and reports when the
+// reservation becomes valid (`retryAfter`): the caller schedules its work at that time. `maxReserved` caps how
+// far below zero reservations may go.
+export const SECOND = 1000;
+export const MINUTE = 60 * SECOND;
+export const HOUR = 60 * MINUTE;
+export const DAY = 24 * HOUR;
+export function checkConfig(c) {
+    if (!c || (c.kind !== "token bucket" && c.kind !== "fixed window"))
+        throw new Error(`rate limit: kind must be "token bucket" or "fixed window"`);
+    if (!(c.rate > 0) || !Number.isFinite(c.rate))
+        throw new Error("rate limit: rate must be a positive number");
+    if (!(c.period > 0) || !Number.isFinite(c.period))
+        throw new Error("rate limit: period must be a positive number of ms");
+    if (c.capacity !== undefined && (!(c.capacity > 0) || !Number.isFinite(c.capacity)))
+        throw new Error("rate limit: capacity must be a positive finite number");
+    if (c.maxReserved !== undefined && (!(c.maxReserved >= 0) || !Number.isFinite(c.maxReserved)))
+        throw new Error("rate limit: maxReserved must be a finite number >= 0");
+    if (c.kind === "fixed window" && c.start !== undefined && !Number.isFinite(c.start))
+        throw new Error("rate limit: start must be a finite number of ms");
+}
+const capacityOf = (c) => c.capacity ?? c.rate;
+/** `count` must be a finite number in [0, capacity] (more than capacity could never succeed). */
+function checkCount(c, count) {
+    if (!(count >= 0) || !Number.isFinite(count))
+        throw new Error("rate limit: count must be a non-negative number");
+    if (count > capacityOf(c))
+        throw new Error(`rate limit: count ${count} exceeds capacity ${capacityOf(c)}`);
+}
+/** The state as of `now` (refilled), without consuming anything. `prev` null = never used: a full bucket. */
+export function refill(c, prev, now) {
+    const cap = capacityOf(c);
+    if (c.kind === "token bucket") {
+        if (!prev)
+            return { value: cap, ts: now };
+        const elapsed = Math.max(0, now - prev.ts);
+        return { value: Math.min(cap, prev.value + (elapsed * c.rate) / c.period), ts: Math.max(now, prev.ts) };
+    }
+    const start = c.start ?? 0;
+    const windowStart = now - (((now - start) % c.period) + c.period) % c.period;
+    if (!prev)
+        return { value: cap, ts: windowStart };
+    const windows = Math.max(0, Math.floor((windowStart - prev.ts) / c.period));
+    return { value: Math.min(cap, prev.value + windows * c.rate), ts: Math.max(prev.ts, windowStart) };
+}
+/** Time until `value` reaches `target` (ms; 0 if already there). */
+function timeUntil(c, s, target, now) {
+    if (s.value >= target)
+        return 0;
+    const missing = target - s.value;
+    if (c.kind === "token bucket")
+        return Math.ceil((missing * c.period) / c.rate);
+    // Fixed window: tokens arrive `rate` at a time, at window boundaries.
+    const windows = Math.ceil(missing / c.rate);
+    return Math.max(0, s.ts + windows * c.period - now);
+}
+/**
+ * Consumes `count` tokens if available. Returns the decision and the state to store (unchanged on refusal:
+ * a refused call costs nothing).
+ */
+export function consume(c, prev, now, count = 1, reserve = false) {
+    checkConfig(c);
+    checkCount(c, count);
+    const s = refill(c, prev, now);
+    if (s.value >= count)
+        return { result: { ok: true }, state: { value: s.value - count, ts: s.ts } };
+    if (reserve) {
+        const next = s.value - count;
+        if (c.maxReserved === undefined || -next <= c.maxReserved) {
+            return { result: { ok: true, retryAfter: timeUntil(c, s, count, now) }, state: { value: next, ts: s.ts } };
+        }
+    }
+    return { result: { ok: false, retryAfter: timeUntil(c, s, count, now) }, state: null };
+}
+/** Whether `count` tokens are available now, without consuming them. */
+export function check(c, prev, now, count = 1) {
+    checkConfig(c);
+    checkCount(c, count);
+    const s = refill(c, prev, now);
+    return s.value >= count ? { ok: true } : { ok: false, retryAfter: timeUntil(c, s, count, now) };
+}

package/dist/component.d.ts

@@ -0,0 +1,275 @@
+import { type RateLimitConfig } from "./algorithms.ts";
+export declare const rateLimitConfigValidator: import("@freecorps/ember-values").Validator<{
+    kind: "token bucket";
+    rate: number;
+    period: number;
+    capacity?: number;
+    maxReserved?: number;
+} | {
+    kind: "fixed window";
+    rate: number;
+    period: number;
+    start?: number;
+    capacity?: number;
+    maxReserved?: number;
+}, "required", NonNullable<"start" | "kind" | "rate" | "period" | "capacity" | "maxReserved" | undefined>>;
+/** Install config: named limits (so calls can pass only the name) and an optional Cloudflare binding. */
+export declare const installConfigValidator: import("@freecorps/ember-values").Validator<{
+    limits?: Record<string, {
+        kind: "token bucket";
+        rate: number;
+        period: number;
+        capacity?: number;
+        maxReserved?: number;
+    } | {
+        kind: "fixed window";
+        rate: number;
+        period: number;
+        start?: number;
+        capacity?: number;
+        maxReserved?: number;
+    }>;
+    binding?: {
+        name: string;
+        period: 60 | 10;
+        limit: number;
+    };
+}, "required", import("@freecorps/ember-values").ObjectFieldPaths<{
+    limits: import("@freecorps/ember-values").Validator<Record<string, {
+        kind: "token bucket";
+        rate: number;
+        period: number;
+        capacity?: number;
+        maxReserved?: number;
+    } | {
+        kind: "fixed window";
+        rate: number;
+        period: number;
+        start?: number;
+        capacity?: number;
+        maxReserved?: number;
+    }>, "optional", never>;
+    /**
+     * A Workers Rate Limiting binding `ember deploy` creates (period 10 or 60 s). Approximate and per location
+     * (Cloudflare docs): for cheap abuse protection in actions/HTTP before touching a shard, not exact quotas.
+     */
+    binding: import("@freecorps/ember-values").Validator<{
+        name: string;
+        period: 60 | 10;
+        limit: number;
+    }, "optional", NonNullable<import("@freecorps/ember-values").ObjectFieldPaths<{
+        name: import("@freecorps/ember-values").Validator<string, "required", never>;
+        limit: import("@freecorps/ember-values").Validator<number, "required", never>;
+        period: import("@freecorps/ember-values").Validator<60 | 10, "required", never>;
+    }> | undefined>>;
+}>>;
+export type RateLimitInstallConfig = {
+    limits?: Record<string, RateLimitConfig>;
+    binding?: {
+        name: string;
+        limit: number;
+        period: 10 | 60;
+    };
+};
+/** Thrown by `limit({ throws: true })` (and `RateLimiter.limit(..., { throws: true })`): `data = { name, retryAfter }`. */
+export declare const RATE_LIMITED = "RateLimited";
+export declare const functions: {
+    lib: {
+        /**
+         * Takes `count` tokens of `name`/`key`. `{ ok: true }` or `{ ok: false, retryAfter }` (ms). With `reserve`,
+         * takes them anyway (going negative) and says when the reservation is valid. With `throws`, a refusal
+         * throws `RateLimited` instead (an app mutation can let it propagate to the client).
+         */
+        limit: import("@freecorps/ember-server").RegisteredMutation<"public", {
+            name: string;
+            key?: string;
+            reserve?: boolean;
+            throws?: boolean;
+            count?: number;
+            config?: {
+                kind: "token bucket";
+                rate: number;
+                period: number;
+                capacity?: number;
+                maxReserved?: number;
+            } | {
+                kind: "fixed window";
+                rate: number;
+                period: number;
+                start?: number;
+                capacity?: number;
+                maxReserved?: number;
+            };
+        }, {
+            ok: boolean;
+            retryAfter: number;
+        } | {
+            ok: boolean;
+            retryAfter?: never;
+        }>;
+        /** Whether `count` tokens are available now, without taking them (reactive in queries). */
+        check: import("@freecorps/ember-server").RegisteredQuery<"public", {
+            name: string;
+            key?: string;
+            count?: number;
+            config?: {
+                kind: "token bucket";
+                rate: number;
+                period: number;
+                capacity?: number;
+                maxReserved?: number;
+            } | {
+                kind: "fixed window";
+                rate: number;
+                period: number;
+                start?: number;
+                capacity?: number;
+                maxReserved?: number;
+            };
+        }, {
+            ok: boolean;
+            retryAfter?: never;
+        } | {
+            ok: boolean;
+            retryAfter: number;
+        }>;
+        /** Tokens available now (may be negative after reservations) and the capacity, e.g. for a UI meter. */
+        getValue: import("@freecorps/ember-server").RegisteredQuery<"public", {
+            name: string;
+            key?: string;
+            config?: {
+                kind: "token bucket";
+                rate: number;
+                period: number;
+                capacity?: number;
+                maxReserved?: number;
+            } | {
+                kind: "fixed window";
+                rate: number;
+                period: number;
+                start?: number;
+                capacity?: number;
+                maxReserved?: number;
+            };
+        }, {
+            value: number;
+            capacity: number;
+            ts: number;
+        }>;
+        /** Forgets `name`/`key` (back to a full bucket). Returns whether a row existed. */
+        reset: import("@freecorps/ember-server").RegisteredMutation<"public", {
+            name: string;
+            key?: string;
+        }, boolean>;
+    };
+};
+export declare const rateLimit: import("@freecorps/ember-server").ComponentDefinition<"rateLimit", {
+    lib: {
+        /**
+         * Takes `count` tokens of `name`/`key`. `{ ok: true }` or `{ ok: false, retryAfter }` (ms). With `reserve`,
+         * takes them anyway (going negative) and says when the reservation is valid. With `throws`, a refusal
+         * throws `RateLimited` instead (an app mutation can let it propagate to the client).
+         */
+        limit: import("@freecorps/ember-server").RegisteredMutation<"public", {
+            name: string;
+            key?: string;
+            reserve?: boolean;
+            throws?: boolean;
+            count?: number;
+            config?: {
+                kind: "token bucket";
+                rate: number;
+                period: number;
+                capacity?: number;
+                maxReserved?: number;
+            } | {
+                kind: "fixed window";
+                rate: number;
+                period: number;
+                start?: number;
+                capacity?: number;
+                maxReserved?: number;
+            };
+        }, {
+            ok: boolean;
+            retryAfter: number;
+        } | {
+            ok: boolean;
+            retryAfter?: never;
+        }>;
+        /** Whether `count` tokens are available now, without taking them (reactive in queries). */
+        check: import("@freecorps/ember-server").RegisteredQuery<"public", {
+            name: string;
+            key?: string;
+            count?: number;
+            config?: {
+                kind: "token bucket";
+                rate: number;
+                period: number;
+                capacity?: number;
+                maxReserved?: number;
+            } | {
+                kind: "fixed window";
+                rate: number;
+                period: number;
+                start?: number;
+                capacity?: number;
+                maxReserved?: number;
+            };
+        }, {
+            ok: boolean;
+            retryAfter?: never;
+        } | {
+            ok: boolean;
+            retryAfter: number;
+        }>;
+        /** Tokens available now (may be negative after reservations) and the capacity, e.g. for a UI meter. */
+        getValue: import("@freecorps/ember-server").RegisteredQuery<"public", {
+            name: string;
+            key?: string;
+            config?: {
+                kind: "token bucket";
+                rate: number;
+                period: number;
+                capacity?: number;
+                maxReserved?: number;
+            } | {
+                kind: "fixed window";
+                rate: number;
+                period: number;
+                start?: number;
+                capacity?: number;
+                maxReserved?: number;
+            };
+        }, {
+            value: number;
+            capacity: number;
+            ts: number;
+        }>;
+        /** Forgets `name`/`key` (back to a full bucket). Returns whether a row existed. */
+        reset: import("@freecorps/ember-server").RegisteredMutation<"public", {
+            name: string;
+            key?: string;
+        }, boolean>;
+    };
+}, {
+    limits?: Record<string, {
+        kind: "token bucket";
+        rate: number;
+        period: number;
+        capacity?: number;
+        maxReserved?: number;
+    } | {
+        kind: "fixed window";
+        rate: number;
+        period: number;
+        start?: number;
+        capacity?: number;
+        maxReserved?: number;
+    }>;
+    binding?: {
+        name: string;
+        period: 60 | 10;
+        limit: number;
+    };
+}, {}>;

package/dist/component.js

@@ -0,0 +1,143 @@
+// The rateLimit component (PLAN §12): one table of (name, key) → tokens, in the caller's shard. `lib:limit` is a
+// mutation, so inside an app mutation it runs in the same transaction: if the app mutation fails afterwards, the
+// tokens are given back (nothing was consumed). Refused calls write nothing.
+import { componentBuilders, defineComponent, defineSchema, defineTable, EmberError, v } from "@freecorps/ember-server";
+import { check, checkConfig, consume, refill } from "./algorithms.js";
+const schema = defineSchema({
+    tables: {
+        /** One row per (name, key) that has been limited; `key` "" is the global limit of `name`. */
+        rateLimits: defineTable({ name: v.string(), key: v.string(), value: v.number(), ts: v.number() }).index("by_name_key", ["name", "key"]),
+    },
+});
+export const rateLimitConfigValidator = v.union(v.object({
+    kind: v.literal("token bucket"),
+    rate: v.number(),
+    period: v.number(),
+    capacity: v.optional(v.number()),
+    maxReserved: v.optional(v.number()),
+}), v.object({
+    kind: v.literal("fixed window"),
+    rate: v.number(),
+    period: v.number(),
+    capacity: v.optional(v.number()),
+    start: v.optional(v.number()),
+    maxReserved: v.optional(v.number()),
+}));
+/** Install config: named limits (so calls can pass only the name) and an optional Cloudflare binding. */
+export const installConfigValidator = v.object({
+    limits: v.optional(v.record(rateLimitConfigValidator)),
+    /**
+     * A Workers Rate Limiting binding `ember deploy` creates (period 10 or 60 s). Approximate and per location
+     * (Cloudflare docs): for cheap abuse protection in actions/HTTP before touching a shard, not exact quotas.
+     */
+    binding: v.optional(v.object({ name: v.string(), limit: v.number(), period: v.union(v.literal(10), v.literal(60)) })),
+});
+const { query, mutation } = componentBuilders();
+const callArgs = {
+    /** Limit name ("sendEmail"). */
+    name: v.string(),
+    /** Per-user/tenant/... key; omitted = one global bucket for `name`. */
+    key: v.optional(v.string()),
+    /** Tokens to take (default 1). */
+    count: v.optional(v.number()),
+    /** The limit's config; omitted = the install config's `limits[name]`. */
+    config: v.optional(rateLimitConfigValidator),
+};
+function configFor(ctx, name, given) {
+    const c = given ?? ctx.component.config?.limits?.[name];
+    if (!c)
+        throw new EmberError("ValidationError", `rateLimit: no config for limit ${JSON.stringify(name)} (pass config, or install it with { limits })`);
+    try {
+        checkConfig(c);
+    }
+    catch (e) {
+        throw new EmberError("ValidationError", e.message);
+    }
+    return c;
+}
+const row = (ctx, name, key) => ctx.db.query("rateLimits").withIndex("by_name_key", (q) => q.eq("name", name).eq("key", key)).unique();
+/** Thrown by `limit({ throws: true })` (and `RateLimiter.limit(..., { throws: true })`): `data = { name, retryAfter }`. */
+export const RATE_LIMITED = "RateLimited";
+export const functions = {
+    lib: {
+        /**
+         * Takes `count` tokens of `name`/`key`. `{ ok: true }` or `{ ok: false, retryAfter }` (ms). With `reserve`,
+         * takes them anyway (going negative) and says when the reservation is valid. With `throws`, a refusal
+         * throws `RateLimited` instead (an app mutation can let it propagate to the client).
+         */
+        limit: mutation({
+            args: { ...callArgs, reserve: v.optional(v.boolean()), throws: v.optional(v.boolean()) },
+            returns: v.object({ ok: v.boolean(), retryAfter: v.optional(v.number()) }),
+            handler: (ctx, a) => {
+                const config = configFor(ctx, a.name, a.config);
+                const key = a.key ?? "";
+                const cur = row(ctx, a.name, key);
+                let decision;
+                try {
+                    decision = consume(config, cur, ctx.now, a.count ?? 1, a.reserve ?? false);
+                }
+                catch (e) {
+                    throw new EmberError("ValidationError", e.message);
+                }
+                const { result, state } = decision;
+                if (!result.ok) {
+                    if (a.throws) {
+                        throw new EmberError(RATE_LIMITED, `Rate limit ${a.name} exceeded; retry in ${result.retryAfter} ms`, { name: a.name, retryAfter: result.retryAfter });
+                    }
+                    return { ok: false, retryAfter: result.retryAfter };
+                }
+                if (state) {
+                    if (cur)
+                        ctx.db.patch(cur._id, { value: state.value, ts: state.ts });
+                    else
+                        ctx.db.insert("rateLimits", { name: a.name, key, value: state.value, ts: state.ts });
+                }
+                return result.retryAfter !== undefined ? { ok: true, retryAfter: result.retryAfter } : { ok: true };
+            },
+        }),
+        /** Whether `count` tokens are available now, without taking them (reactive in queries). */
+        check: query({
+            args: callArgs,
+            returns: v.object({ ok: v.boolean(), retryAfter: v.optional(v.number()) }),
+            handler: (ctx, a) => {
+                const config = configFor(ctx, a.name, a.config);
+                let r;
+                try {
+                    r = check(config, row(ctx, a.name, a.key ?? ""), ctx.now, a.count ?? 1);
+                }
+                catch (e) {
+                    throw new EmberError("ValidationError", e.message);
+                }
+                return r.ok ? { ok: true } : { ok: false, retryAfter: r.retryAfter };
+            },
+        }),
+        /** Tokens available now (may be negative after reservations) and the capacity, e.g. for a UI meter. */
+        getValue: query({
+            args: { name: v.string(), key: v.optional(v.string()), config: v.optional(rateLimitConfigValidator) },
+            returns: v.object({ value: v.number(), capacity: v.number(), ts: v.number() }),
+            handler: (ctx, a) => {
+                const config = configFor(ctx, a.name, a.config);
+                const s = refill(config, row(ctx, a.name, a.key ?? ""), ctx.now);
+                return { value: s.value, capacity: config.capacity ?? config.rate, ts: s.ts };
+            },
+        }),
+        /** Forgets `name`/`key` (back to a full bucket). Returns whether a row existed. */
+        reset: mutation({
+            args: { name: v.string(), key: v.optional(v.string()) },
+            returns: v.boolean(),
+            handler: (ctx, a) => {
+                const cur = row(ctx, a.name, a.key ?? "");
+                if (cur)
+                    ctx.db.delete(cur._id);
+                return !!cur;
+            },
+        }),
+    },
+};
+export const rateLimit = defineComponent({
+    name: "rateLimit",
+    schema,
+    functions,
+    config: v.optional(installConfigValidator),
+    bindings: (config) => (config?.binding ? [{ type: "ratelimit", name: config.binding.name, limit: config.binding.limit, period: config.binding.period }] : []),
+});

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * `@freecorps/ember-rate-limit`: rate limiting as an Ember component (PLAN §12), like Convex's rate-limiter.
+ *
+ *   // ember/ember.config.ts
+ *   export default defineApp().use(rateLimit);
+ *
+ *   // ember/limits.ts
+ *   export const limiter = new RateLimiter(components.rateLimit, {
+ *     sendMessage: { kind: "token bucket", rate: 10, period: MINUTE, capacity: 3 },
+ *     signUp: { kind: "fixed window", rate: 100, period: HOUR },
+ *   });
+ *
+ *   // in a mutation (synchronous, same transaction: a later failure gives the tokens back)
+ *   const { ok, retryAfter } = limiter.limit(ctx, "sendMessage", { key: userId });
+ *   // in an action (a separate transaction on the action's shard)
+ *   await limiter.limit(ctx, "signUp");
+ *
+ * State lives in the caller's shard: a limit is exact per shard. For a limit across shards, call it on one shard
+ * from an action (`ctx.onShard("global:main")`), or use the Cloudflare binding (approximate, per location).
+ */
+import { type FunctionReference } from "@freecorps/ember-server";
+import type { RateLimitConfig, ReserveResult } from "./algorithms.ts";
+export * from "./algorithms.ts";
+export { rateLimit, functions as rateLimitFunctions, rateLimitConfigValidator, installConfigValidator, RATE_LIMITED, type RateLimitInstallConfig } from "./component.ts";
+type LimitArgs = {
+    name: string;
+    key?: string;
+    count?: number;
+    config?: RateLimitConfig;
+    reserve?: boolean;
+    throws?: boolean;
+};
+type CheckArgs = {
+    name: string;
+    key?: string;
+    count?: number;
+    config?: RateLimitConfig;
+};
+type Result = {
+    ok: boolean;
+    retryAfter?: number;
+};
+/** What `components.<name>` of the rateLimit component looks like (structural: any install name works). */
+export interface RateLimitComponentApi {
+    lib: {
+        limit: FunctionReference<"mutation", "public", LimitArgs, Result>;
+        check: FunctionReference<"query", "public", CheckArgs, Result>;
+        getValue: FunctionReference<"query", "public", {
+            name: string;
+            key?: string;
+            config?: RateLimitConfig;
+        }, {
+            value: number;
+            capacity: number;
+            ts: number;
+        }>;
+        reset: FunctionReference<"mutation", "public", {
+            name: string;
+            key?: string;
+        }, boolean>;
+    };
+}
+/** Mutation/query ctx: `ctx.run*` returns values (same transaction). */
+type SyncCtx = {
+    db: unknown;
+    runQuery(fn: any, args?: any): any;
+    runMutation?(fn: any, args?: any): any;
+};
+/** Action ctx: `ctx.run*` returns Promises (own transaction on the action's shard). */
+type AsyncCtx = {
+    runAction(fn: any, args?: any): Promise<any>;
+    runQuery(fn: any, args?: any): Promise<any>;
+    runMutation(fn: any, args?: any): Promise<any>;
+};
+export type LimitOptions = {
+    key?: string;
+    count?: number;
+    reserve?: boolean;
+    throws?: boolean;
+};
+/** Throws `RateLimited` for a refused result (what `throws: true` does inside the component). */
+export declare function assertAllowed(name: string, r: Result): void;
+/**
+ * Typed helper over an installed rateLimit component: limits are declared once here and sent with each call,
+ * so they can change without redeploying the component's config. Works in mutations (sync) and actions (async).
+ */
+export declare class RateLimiter<Limits extends Record<string, RateLimitConfig>> {
+    readonly component: RateLimitComponentApi;
+    readonly limits: Limits;
+    constructor(component: RateLimitComponentApi, limits: Limits);
+    private args;
+    /** Takes tokens. In a mutation: synchronous, same transaction. In an action: a Promise. */
+    limit(ctx: SyncCtx, name: keyof Limits & string, opts?: LimitOptions): ReserveResult;
+    limit(ctx: AsyncCtx, name: keyof Limits & string, opts?: LimitOptions): Promise<ReserveResult>;
+    /** Checks without taking tokens. Reactive inside queries. */
+    check(ctx: SyncCtx, name: keyof Limits & string, opts?: Pick<LimitOptions, "key" | "count">): Result;
+    check(ctx: AsyncCtx, name: keyof Limits & string, opts?: Pick<LimitOptions, "key" | "count">): Promise<Result>;
+    /** Tokens left (and capacity), e.g. for a UI. */
+    getValue(ctx: SyncCtx, name: keyof Limits & string, opts?: {
+        key?: string;
+    }): {
+        value: number;
+        capacity: number;
+        ts: number;
+    };
+    getValue(ctx: AsyncCtx, name: keyof Limits & string, opts?: {
+        key?: string;
+    }): Promise<{
+        value: number;
+        capacity: number;
+        ts: number;
+    }>;
+    /** Back to a full bucket. */
+    reset(ctx: SyncCtx, name: keyof Limits & string, opts?: {
+        key?: string;
+    }): boolean;
+    reset(ctx: AsyncCtx, name: keyof Limits & string, opts?: {
+        key?: string;
+    }): Promise<boolean>;
+}
+/** The Workers Rate Limiting binding (`env.<name>.limit({ key })`). */
+export interface RateLimitBinding {
+    limit(o: {
+        key: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+}
+/**
+ * Action/HTTP-side check against the Cloudflare Rate Limiting binding the component asked for
+ * (`app.use(rateLimit, { config: { binding: { name, limit, period } } })`). Approximate and per Cloudflare
+ * location: use it to shed abusive traffic before it reaches a shard; use `RateLimiter` for exact quotas.
+ */
+export declare function edgeLimit(ctx: {
+    env: Record<string, unknown>;
+}, binding: string, key: string): Promise<{
+    ok: boolean;
+}>;

package/dist/index.js

@@ -0,0 +1,87 @@
+/**
+ * `@freecorps/ember-rate-limit`: rate limiting as an Ember component (PLAN §12), like Convex's rate-limiter.
+ *
+ *   // ember/ember.config.ts
+ *   export default defineApp().use(rateLimit);
+ *
+ *   // ember/limits.ts
+ *   export const limiter = new RateLimiter(components.rateLimit, {
+ *     sendMessage: { kind: "token bucket", rate: 10, period: MINUTE, capacity: 3 },
+ *     signUp: { kind: "fixed window", rate: 100, period: HOUR },
+ *   });
+ *
+ *   // in a mutation (synchronous, same transaction: a later failure gives the tokens back)
+ *   const { ok, retryAfter } = limiter.limit(ctx, "sendMessage", { key: userId });
+ *   // in an action (a separate transaction on the action's shard)
+ *   await limiter.limit(ctx, "signUp");
+ *
+ * State lives in the caller's shard: a limit is exact per shard. For a limit across shards, call it on one shard
+ * from an action (`ctx.onShard("global:main")`), or use the Cloudflare binding (approximate, per location).
+ */
+import { EmberError } from "@freecorps/ember-server";
+import { RATE_LIMITED } from "./component.js";
+export * from "./algorithms.js";
+export { rateLimit, functions as rateLimitFunctions, rateLimitConfigValidator, installConfigValidator, RATE_LIMITED } from "./component.js";
+/** Throws `RateLimited` for a refused result (what `throws: true` does inside the component). */
+export function assertAllowed(name, r) {
+    if (!r.ok)
+        throw new EmberError(RATE_LIMITED, `Rate limit ${name} exceeded; retry in ${r.retryAfter} ms`, { name, retryAfter: r.retryAfter });
+}
+/**
+ * Typed helper over an installed rateLimit component: limits are declared once here and sent with each call,
+ * so they can change without redeploying the component's config. Works in mutations (sync) and actions (async).
+ */
+export class RateLimiter {
+    component;
+    limits;
+    constructor(component, limits) {
+        this.component = component;
+        this.limits = limits;
+    }
+    args(name, o = {}) {
+        const config = this.limits[name];
+        if (!config)
+            throw new Error(`RateLimiter: unknown limit ${JSON.stringify(name)}`);
+        const a = { name, config };
+        if (o.key !== undefined)
+            a.key = o.key;
+        if (o.count !== undefined)
+            a.count = o.count;
+        if (o.reserve)
+            a.reserve = true;
+        if (o.throws)
+            a.throws = true;
+        return a;
+    }
+    limit(ctx, name, opts) {
+        if (!ctx.runMutation)
+            throw new Error("RateLimiter.limit needs a mutation or action ctx (queries cannot take tokens: use check)");
+        return ctx.runMutation(this.component.lib.limit, this.args(name, opts));
+    }
+    check(ctx, name, opts = {}) {
+        const { reserve: _r, throws: _t, ...a } = this.args(name, opts);
+        return ctx.runQuery(this.component.lib.check, a);
+    }
+    getValue(ctx, name, opts = {}) {
+        const { name: n, config, key } = this.args(name, opts);
+        return ctx.runQuery(this.component.lib.getValue, key !== undefined ? { name: n, config, key } : { name: n, config });
+    }
+    reset(ctx, name, opts = {}) {
+        if (!ctx.runMutation)
+            throw new Error("RateLimiter.reset needs a mutation or action ctx");
+        return ctx.runMutation(this.component.lib.reset, opts.key !== undefined ? { name, key: opts.key } : { name });
+    }
+}
+/**
+ * Action/HTTP-side check against the Cloudflare Rate Limiting binding the component asked for
+ * (`app.use(rateLimit, { config: { binding: { name, limit, period } } })`). Approximate and per Cloudflare
+ * location: use it to shed abusive traffic before it reaches a shard; use `RateLimiter` for exact quotas.
+ */
+export async function edgeLimit(ctx, binding, key) {
+    const b = ctx.env[binding];
+    if (!b || typeof b.limit !== "function") {
+        throw new EmberError("ValidationError", `edgeLimit: no Rate Limiting binding ${binding} (install rateLimit with { binding } and deploy)`);
+    }
+    const r = await b.limit({ key });
+    return { ok: !!r.success };
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@freecorps/ember-rate-limit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Rate limiting component for Ember: token bucket and fixed window per key, stored in the shard and transactional inside mutations; optional Cloudflare Rate Limiting binding helper.",
+  "keywords": [
+    "ember",
+    "convex",
+    "cloudflare",
+    "workers",
+    "component",
+    "rate-limit",
+    "rate-limiter",
+    "token-bucket"
+  ],
+  "homepage": "https://github.com/freecorps/ember/tree/main/packages/rate-limit#readme",
+  "bugs": {
+    "url": "https://github.com/freecorps/ember/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freecorps/ember.git",
+    "directory": "packages/rate-limit"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@freecorps/ember-server": "0.3.0",
+    "@freecorps/ember-values": "0.3.0"
+  }
+}