@vllnt/convex-buckets 0.1.0-canary.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +157 -0
  3. package/dist/client/index.d.ts +79 -0
  4. package/dist/client/index.d.ts.map +1 -0
  5. package/dist/client/index.js +86 -0
  6. package/dist/client/index.js.map +1 -0
  7. package/dist/client/types.d.ts +28 -0
  8. package/dist/client/types.d.ts.map +1 -0
  9. package/dist/client/types.js +3 -0
  10. package/dist/client/types.js.map +1 -0
  11. package/dist/component/_generated/api.d.ts +38 -0
  12. package/dist/component/_generated/api.d.ts.map +1 -0
  13. package/dist/component/_generated/api.js +31 -0
  14. package/dist/component/_generated/api.js.map +1 -0
  15. package/dist/component/_generated/component.d.ts +102 -0
  16. package/dist/component/_generated/component.d.ts.map +1 -0
  17. package/dist/component/_generated/component.js +11 -0
  18. package/dist/component/_generated/component.js.map +1 -0
  19. package/dist/component/_generated/dataModel.d.ts +46 -0
  20. package/dist/component/_generated/dataModel.d.ts.map +1 -0
  21. package/dist/component/_generated/dataModel.js +11 -0
  22. package/dist/component/_generated/dataModel.js.map +1 -0
  23. package/dist/component/_generated/server.d.ts +133 -0
  24. package/dist/component/_generated/server.d.ts.map +1 -0
  25. package/dist/component/_generated/server.js +80 -0
  26. package/dist/component/_generated/server.js.map +1 -0
  27. package/dist/component/convex.config.d.ts +3 -0
  28. package/dist/component/convex.config.d.ts.map +1 -0
  29. package/dist/component/convex.config.js +4 -0
  30. package/dist/component/convex.config.js.map +1 -0
  31. package/dist/component/mutations.d.ts +44 -0
  32. package/dist/component/mutations.d.ts.map +1 -0
  33. package/dist/component/mutations.js +244 -0
  34. package/dist/component/mutations.js.map +1 -0
  35. package/dist/component/queries.d.ts +41 -0
  36. package/dist/component/queries.d.ts.map +1 -0
  37. package/dist/component/queries.js +101 -0
  38. package/dist/component/queries.js.map +1 -0
  39. package/dist/component/schema.d.ts +47 -0
  40. package/dist/component/schema.d.ts.map +1 -0
  41. package/dist/component/schema.js +31 -0
  42. package/dist/component/schema.js.map +1 -0
  43. package/dist/component/validators.d.ts +26 -0
  44. package/dist/component/validators.d.ts.map +1 -0
  45. package/dist/component/validators.js +16 -0
  46. package/dist/component/validators.js.map +1 -0
  47. package/dist/shared.d.ts +13 -0
  48. package/dist/shared.d.ts.map +1 -0
  49. package/dist/shared.js +22 -0
  50. package/dist/shared.js.map +1 -0
  51. package/package.json +87 -0
  52. package/src/client/index.ts +247 -0
  53. package/src/client/types.ts +33 -0
  54. package/src/component/_generated/api.ts +54 -0
  55. package/src/component/_generated/component.ts +123 -0
  56. package/src/component/_generated/dataModel.ts +60 -0
  57. package/src/component/_generated/server.ts +169 -0
  58. package/src/component/convex.config.ts +5 -0
  59. package/src/component/mutations.ts +316 -0
  60. package/src/component/queries.ts +112 -0
  61. package/src/component/schema.ts +35 -0
  62. package/src/component/validators.ts +22 -0
  63. package/src/shared.ts +28 -0
  64. package/src/test.ts +13 -0
@@ -0,0 +1,316 @@
1
+ import { ConvexError, v } from "convex/values";
2
+
3
+ import {
4
+ DEFAULT_ERASE_BATCH,
5
+ MAX_ERASE_BATCH,
6
+ MAX_REF_LENGTH,
7
+ } from "../shared";
8
+
9
+ import { internal } from "./_generated/api";
10
+ import type { Id } from "./_generated/dataModel";
11
+ import {
12
+ internalMutation,
13
+ mutation,
14
+ type MutationCtx,
15
+ } from "./_generated/server";
16
+
17
+ function findBucket(
18
+ ctx: MutationCtx,
19
+ ref: { bucketRef: string; scope: string },
20
+ ) {
21
+ return ctx.db
22
+ .query("buckets")
23
+ .withIndex("by_scope_ref", (q) =>
24
+ q.eq("scope", ref.scope).eq("bucketRef", ref.bucketRef),
25
+ )
26
+ .unique();
27
+ }
28
+
29
+ function findMember(
30
+ ctx: MutationCtx,
31
+ ref: { bucketRef: string; scope: string; subjectRef: string },
32
+ ) {
33
+ return ctx.db
34
+ .query("members")
35
+ .withIndex("by_bucket_subject", (q) =>
36
+ q
37
+ .eq("scope", ref.scope)
38
+ .eq("bucketRef", ref.bucketRef)
39
+ .eq("subjectRef", ref.subjectRef),
40
+ )
41
+ .unique();
42
+ }
43
+
44
+ function membersInBucket(
45
+ ctx: MutationCtx,
46
+ ref: { bucketRef: string; scope: string },
47
+ ) {
48
+ return ctx.db
49
+ .query("members")
50
+ .withIndex("by_bucket", (q) =>
51
+ q.eq("scope", ref.scope).eq("bucketRef", ref.bucketRef),
52
+ );
53
+ }
54
+
55
+ function fail(code: string, message: string): never {
56
+ throw new ConvexError({ code, message });
57
+ }
58
+
59
+ function requireRef(value: string, name: string): void {
60
+ if (value.length === 0 || value.length > MAX_REF_LENGTH) {
61
+ fail(
62
+ "INVALID_REF",
63
+ `${name} must be 1..${String(MAX_REF_LENGTH)} characters`,
64
+ );
65
+ }
66
+ }
67
+
68
+ function parseBatch(batch: number | undefined): number {
69
+ const raw = batch ?? DEFAULT_ERASE_BATCH;
70
+ if (!Number.isSafeInteger(raw)) {
71
+ fail("INVALID_BATCH", "batch must be a positive integer");
72
+ }
73
+ if (raw < 1) {
74
+ fail("INVALID_BATCH", "batch must be a positive integer");
75
+ }
76
+ return Math.min(raw, MAX_ERASE_BATCH);
77
+ }
78
+
79
+ export const open = mutation({
80
+ args: {
81
+ bucketRef: v.optional(v.string()),
82
+ capacity: v.optional(v.number()),
83
+ scope: v.string(),
84
+ },
85
+ handler: async (ctx, arguments_) => {
86
+ requireRef(arguments_.scope, "scope");
87
+ if (
88
+ arguments_.capacity !== undefined &&
89
+ (!Number.isSafeInteger(arguments_.capacity) || arguments_.capacity < 1)
90
+ ) {
91
+ fail("INVALID_CAPACITY", "capacity must be a positive integer");
92
+ }
93
+ const bucketRef = arguments_.bucketRef ?? crypto.randomUUID();
94
+ requireRef(bucketRef, "bucketRef");
95
+ const existing = await findBucket(ctx, {
96
+ bucketRef,
97
+ scope: arguments_.scope,
98
+ });
99
+ if (existing !== null) {
100
+ fail(
101
+ "BUCKET_EXISTS",
102
+ "a bucket with this ref already exists in the scope",
103
+ );
104
+ }
105
+ await ctx.db.insert("buckets", {
106
+ bucketRef,
107
+ capacity: arguments_.capacity,
108
+ memberCount: 0,
109
+ openedAt: Date.now(),
110
+ scope: arguments_.scope,
111
+ status: "open",
112
+ });
113
+ return bucketRef;
114
+ },
115
+ returns: v.string(),
116
+ });
117
+
118
+ export const join = mutation({
119
+ args: {
120
+ bucketRef: v.string(),
121
+ scope: v.string(),
122
+ subjectRef: v.string(),
123
+ },
124
+ handler: async (ctx, arguments_) => {
125
+ requireRef(arguments_.scope, "scope");
126
+ requireRef(arguments_.bucketRef, "bucketRef");
127
+ requireRef(arguments_.subjectRef, "subjectRef");
128
+ const bucket = await findBucket(ctx, arguments_);
129
+ if (bucket === null) {
130
+ return { joined: false, reason: "missing" };
131
+ }
132
+ if (bucket.status !== "open") {
133
+ return { joined: false, reason: bucket.status };
134
+ }
135
+ const existing = await findMember(ctx, arguments_);
136
+ if (existing !== null) {
137
+ return { joined: false, reason: "already_member" };
138
+ }
139
+ if (
140
+ bucket.capacity !== undefined &&
141
+ bucket.memberCount >= bucket.capacity
142
+ ) {
143
+ return { joined: false, reason: "full" };
144
+ }
145
+ await ctx.db.insert("members", { ...arguments_, joinedAt: Date.now() });
146
+ await ctx.db.patch("buckets", bucket._id, {
147
+ memberCount: bucket.memberCount + 1,
148
+ });
149
+ return { joined: true };
150
+ },
151
+ returns: v.object({ joined: v.boolean(), reason: v.optional(v.string()) }),
152
+ });
153
+
154
+ export const leave = mutation({
155
+ args: {
156
+ bucketRef: v.string(),
157
+ scope: v.string(),
158
+ subjectRef: v.string(),
159
+ },
160
+ handler: async (ctx, arguments_) => {
161
+ requireRef(arguments_.scope, "scope");
162
+ requireRef(arguments_.bucketRef, "bucketRef");
163
+ requireRef(arguments_.subjectRef, "subjectRef");
164
+ const bucket = await findBucket(ctx, arguments_);
165
+ if (bucket === null || bucket.status === "closed") {
166
+ return false;
167
+ }
168
+ const existing = await findMember(ctx, arguments_);
169
+ if (existing === null) {
170
+ return false;
171
+ }
172
+ await ctx.db.delete("members", existing._id);
173
+ await ctx.db.patch("buckets", bucket._id, {
174
+ memberCount: Math.max(bucket.memberCount - 1, 0),
175
+ });
176
+ return true;
177
+ },
178
+ returns: v.boolean(),
179
+ });
180
+
181
+ export const lock = mutation({
182
+ args: { bucketRef: v.string(), scope: v.string() },
183
+ handler: async (ctx, arguments_) => {
184
+ requireRef(arguments_.scope, "scope");
185
+ requireRef(arguments_.bucketRef, "bucketRef");
186
+ const bucket = await findBucket(ctx, arguments_);
187
+ if (bucket?.status !== "open") {
188
+ return false;
189
+ }
190
+ await ctx.db.patch("buckets", bucket._id, {
191
+ lockedAt: Date.now(),
192
+ status: "locked",
193
+ });
194
+ return true;
195
+ },
196
+ returns: v.boolean(),
197
+ });
198
+
199
+ export const close = mutation({
200
+ args: { bucketRef: v.string(), scope: v.string() },
201
+ handler: async (ctx, arguments_) => {
202
+ requireRef(arguments_.scope, "scope");
203
+ requireRef(arguments_.bucketRef, "bucketRef");
204
+ const bucket = await findBucket(ctx, arguments_);
205
+ if (bucket === null || bucket.status === "closed") {
206
+ return false;
207
+ }
208
+ await ctx.db.patch("buckets", bucket._id, {
209
+ closedAt: Date.now(),
210
+ status: "closed",
211
+ });
212
+ return true;
213
+ },
214
+ returns: v.boolean(),
215
+ });
216
+
217
+ export const eraseBucket = mutation({
218
+ args: {
219
+ batch: v.optional(v.number()),
220
+ bucketRef: v.string(),
221
+ scope: v.string(),
222
+ },
223
+ handler: async (ctx, arguments_) => {
224
+ requireRef(arguments_.scope, "scope");
225
+ requireRef(arguments_.bucketRef, "bucketRef");
226
+ const batch = parseBatch(arguments_.batch);
227
+ const bucket = await findBucket(ctx, arguments_);
228
+ if (bucket === null) return 0;
229
+ return eraseBucketBatch(ctx, bucket._id, batch);
230
+ },
231
+ returns: v.number(),
232
+ });
233
+
234
+ async function eraseBucketBatch(
235
+ ctx: MutationCtx,
236
+ bucketId: Id<"buckets">,
237
+ batch: number,
238
+ ): Promise<number> {
239
+ const bucket = await ctx.db.get("buckets", bucketId);
240
+ if (bucket === null) return 0;
241
+ const members = await membersInBucket(ctx, bucket).take(batch);
242
+ await Promise.all(
243
+ members.map((member) => ctx.db.delete("members", member._id)),
244
+ );
245
+ if (members.length < batch) {
246
+ await ctx.db.delete("buckets", bucketId);
247
+ } else {
248
+ await ctx.db.patch("buckets", bucketId, {
249
+ closedAt: bucket.closedAt ?? Date.now(),
250
+ memberCount: Math.max(0, bucket.memberCount - members.length),
251
+ status: "closed",
252
+ });
253
+ await ctx.scheduler.runAfter(0, internal.mutations.continueEraseBucket, {
254
+ batch,
255
+ bucketId,
256
+ });
257
+ }
258
+ return members.length;
259
+ }
260
+
261
+ export const continueEraseBucket = internalMutation({
262
+ args: { batch: v.number(), bucketId: v.id("buckets") },
263
+ handler: async (ctx, arguments_) =>
264
+ eraseBucketBatch(ctx, arguments_.bucketId, parseBatch(arguments_.batch)),
265
+ returns: v.number(),
266
+ });
267
+
268
+ function subjectMembers(
269
+ ctx: MutationCtx,
270
+ ref: { scope: string; subjectRef: string },
271
+ ) {
272
+ return ctx.db
273
+ .query("members")
274
+ .withIndex("by_subject", (q) =>
275
+ q.eq("scope", ref.scope).eq("subjectRef", ref.subjectRef),
276
+ );
277
+ }
278
+
279
+ export const eraseSubject = mutation({
280
+ args: {
281
+ batch: v.optional(v.number()),
282
+ scope: v.string(),
283
+ subjectRef: v.string(),
284
+ },
285
+ handler: async (ctx, ref) => {
286
+ requireRef(ref.scope, "scope");
287
+ requireRef(ref.subjectRef, "subjectRef");
288
+ const batch = parseBatch(ref.batch);
289
+ return eraseSubjectBatch(ctx, { ...ref, batch });
290
+ },
291
+ returns: v.number(),
292
+ });
293
+
294
+ type SubjectBatch = {
295
+ batch: number;
296
+ scope: string;
297
+ subjectRef: string;
298
+ };
299
+
300
+ async function eraseSubjectBatch(
301
+ ctx: MutationCtx,
302
+ ref: SubjectBatch,
303
+ ): Promise<number> {
304
+ const memberships = await subjectMembers(ctx, ref).take(ref.batch);
305
+ await Promise.all(
306
+ memberships.map(async (membership) => {
307
+ await ctx.db.delete("members", membership._id);
308
+ const bucket = await findBucket(ctx, membership);
309
+ if (bucket !== null)
310
+ await ctx.db.patch("buckets", bucket._id, {
311
+ memberCount: Math.max(0, bucket.memberCount - 1),
312
+ });
313
+ }),
314
+ );
315
+ return memberships.length;
316
+ }
@@ -0,0 +1,112 @@
1
+ import { paginationOptsValidator } from "convex/server";
2
+ import { ConvexError, v } from "convex/values";
3
+
4
+ import { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, MAX_REF_LENGTH } from "../shared";
5
+
6
+ import { query } from "./_generated/server";
7
+ import { bucketState, memberState } from "./validators";
8
+
9
+ function fail(code: string, message: string): never {
10
+ throw new ConvexError({ code, message });
11
+ }
12
+
13
+ export const get = query({
14
+ args: { bucketRef: v.string(), scope: v.string() },
15
+ handler: async (ctx, arguments_) => {
16
+ [arguments_.scope, arguments_.bucketRef].forEach((value) => {
17
+ if (value.length === 0 || value.length > MAX_REF_LENGTH)
18
+ fail("INVALID_REF", "refs must be 1..256 characters");
19
+ });
20
+ const bucket = await ctx.db
21
+ .query("buckets")
22
+ .withIndex("by_scope_ref", (q) =>
23
+ q.eq("scope", arguments_.scope).eq("bucketRef", arguments_.bucketRef),
24
+ )
25
+ .unique();
26
+ if (bucket === null) {
27
+ // eslint-disable-next-line unicorn/no-null -- Convex serializes null; undefined is not a valid cursor/result.
28
+ return null;
29
+ }
30
+ return {
31
+ bucketRef: bucket.bucketRef,
32
+ capacity: bucket.capacity,
33
+ closedAt: bucket.closedAt,
34
+ lockedAt: bucket.lockedAt,
35
+ memberCount: bucket.memberCount,
36
+ openedAt: bucket.openedAt,
37
+ status: bucket.status,
38
+ };
39
+ },
40
+ returns: v.union(v.null(), bucketState),
41
+ });
42
+
43
+ export const paginateMembers = query({
44
+ args: {
45
+ bucketRef: v.string(),
46
+ paginationOpts: paginationOptsValidator,
47
+ scope: v.string(),
48
+ },
49
+ handler: async (ctx, arguments_) => {
50
+ [arguments_.scope, arguments_.bucketRef].forEach((value) => {
51
+ if (value.length === 0 || value.length > MAX_REF_LENGTH)
52
+ fail("INVALID_REF", "refs must be 1..256 characters");
53
+ });
54
+ const size = arguments_.paginationOpts.numItems;
55
+ if (!Number.isSafeInteger(size) || size < 1 || size > MAX_LIST_LIMIT) {
56
+ fail("INVALID_LIMIT", `numItems must be 1..${String(MAX_LIST_LIMIT)}`);
57
+ }
58
+ const result = await ctx.db
59
+ .query("members")
60
+ .withIndex("by_bucket", (q) =>
61
+ q.eq("scope", arguments_.scope).eq("bucketRef", arguments_.bucketRef),
62
+ )
63
+ .paginate(arguments_.paginationOpts);
64
+ return {
65
+ continueCursor: result.continueCursor,
66
+ isDone: result.isDone,
67
+ page: result.page.map((member) => ({
68
+ joinedAt: member.joinedAt,
69
+ subjectRef: member.subjectRef,
70
+ })),
71
+ };
72
+ },
73
+ returns: v.object({
74
+ continueCursor: v.string(),
75
+ isDone: v.boolean(),
76
+ page: v.array(memberState),
77
+ }),
78
+ });
79
+
80
+ /** Bounded preview; use paginateMembers to list every member. */
81
+ export const listMembers = query({
82
+ args: {
83
+ bucketRef: v.string(),
84
+ limit: v.optional(v.number()),
85
+ scope: v.string(),
86
+ },
87
+ handler: async (ctx, arguments_) => {
88
+ [arguments_.scope, arguments_.bucketRef].forEach((value) => {
89
+ if (value.length === 0 || value.length > MAX_REF_LENGTH)
90
+ fail("INVALID_REF", "refs must be 1..256 characters");
91
+ });
92
+ const raw = arguments_.limit ?? DEFAULT_LIST_LIMIT;
93
+ if (!Number.isSafeInteger(raw)) {
94
+ fail("INVALID_LIMIT", "limit must be a positive integer");
95
+ }
96
+ if (raw < 1) {
97
+ fail("INVALID_LIMIT", "limit must be a positive integer");
98
+ }
99
+ const limit = Math.min(raw, MAX_LIST_LIMIT);
100
+ const members = await ctx.db
101
+ .query("members")
102
+ .withIndex("by_bucket", (q) =>
103
+ q.eq("scope", arguments_.scope).eq("bucketRef", arguments_.bucketRef),
104
+ )
105
+ .take(limit);
106
+ return members.map((member) => ({
107
+ joinedAt: member.joinedAt,
108
+ subjectRef: member.subjectRef,
109
+ }));
110
+ },
111
+ returns: v.array(memberState),
112
+ });
@@ -0,0 +1,35 @@
1
+ import { defineSchema, defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+
4
+ /**
5
+ * Sandboxed tables — ephemeral groups of opaque `subjectRef`s. Distinct from
6
+ * `convex-memberships` (standing org/roles) and `@convex-dev/presence` (liveness).
7
+ *
8
+ * `memberCount` lives on the bucket row so join capacity is OCC-safe: concurrent
9
+ * joins patch the same document and Convex retries the loser.
10
+ */
11
+ export default defineSchema({
12
+ buckets: defineTable({
13
+ bucketRef: v.string(),
14
+ capacity: v.optional(v.number()),
15
+ closedAt: v.optional(v.number()),
16
+ lockedAt: v.optional(v.number()),
17
+ memberCount: v.number(),
18
+ openedAt: v.number(),
19
+ scope: v.string(),
20
+ status: v.union(
21
+ v.literal("closed"),
22
+ v.literal("locked"),
23
+ v.literal("open"),
24
+ ),
25
+ }).index("by_scope_ref", ["scope", "bucketRef"]),
26
+ members: defineTable({
27
+ bucketRef: v.string(),
28
+ joinedAt: v.number(),
29
+ scope: v.string(),
30
+ subjectRef: v.string(),
31
+ })
32
+ .index("by_bucket", ["scope", "bucketRef"])
33
+ .index("by_bucket_subject", ["scope", "bucketRef", "subjectRef"])
34
+ .index("by_subject", ["scope", "subjectRef"]),
35
+ });
@@ -0,0 +1,22 @@
1
+ import { v } from "convex/values";
2
+
3
+ export const bucketStatus = v.union(
4
+ v.literal("open"),
5
+ v.literal("locked"),
6
+ v.literal("closed"),
7
+ );
8
+
9
+ export const bucketState = v.object({
10
+ bucketRef: v.string(),
11
+ capacity: v.optional(v.number()),
12
+ closedAt: v.optional(v.number()),
13
+ lockedAt: v.optional(v.number()),
14
+ memberCount: v.number(),
15
+ openedAt: v.number(),
16
+ status: bucketStatus,
17
+ });
18
+
19
+ export const memberState = v.object({
20
+ joinedAt: v.number(),
21
+ subjectRef: v.string(),
22
+ });
package/src/shared.ts ADDED
@@ -0,0 +1,28 @@
1
+ /** Shared constants used by both `client/` and `component/`. */
2
+
3
+ export const COMPONENT_NAME = "buckets";
4
+
5
+ /** Default namespace when the host does not scope a bucket. */
6
+ export const DEFAULT_SCOPE = "global";
7
+
8
+ export const MAX_REF_LENGTH = 256;
9
+ export const DEFAULT_ERASE_BATCH = 200;
10
+ export const MAX_ERASE_BATCH = 500;
11
+ export const DEFAULT_LIST_LIMIT = 100;
12
+ export const MAX_LIST_LIMIT = 500;
13
+
14
+ export type BucketStatus = "closed" | "locked" | "open";
15
+
16
+ export function clampEraseBatch(batch: number): number {
17
+ if (!Number.isInteger(batch) || batch < 1) {
18
+ throw new Error("INVALID_BATCH: batch must be a positive integer");
19
+ }
20
+ return Math.min(batch, MAX_ERASE_BATCH);
21
+ }
22
+
23
+ export function clampListLimit(limit: number): number {
24
+ if (!Number.isInteger(limit) || limit < 1) {
25
+ throw new Error("INVALID_LIMIT: limit must be a positive integer");
26
+ }
27
+ return Math.min(limit, MAX_LIST_LIMIT);
28
+ }
package/src/test.ts ADDED
@@ -0,0 +1,13 @@
1
+ import type { GenericSchema, SchemaDefinition } from "convex/server";
2
+ import type { TestConvex } from "convex-test";
3
+
4
+ import schema from "./component/schema";
5
+
6
+ const modules = import.meta.glob("./component/**/*.ts");
7
+
8
+ export function register<TSchema extends GenericSchema>(
9
+ t: TestConvex<SchemaDefinition<TSchema, boolean>>,
10
+ name = "buckets",
11
+ ): void {
12
+ t.registerComponent(name, schema, modules);
13
+ }