@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,101 @@
1
+ import { paginationOptsValidator } from "convex/server";
2
+ import { ConvexError, v } from "convex/values";
3
+ import { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, MAX_REF_LENGTH } from "../shared";
4
+ import { query } from "./_generated/server";
5
+ import { bucketState, memberState } from "./validators";
6
+ function fail(code, message) {
7
+ throw new ConvexError({ code, message });
8
+ }
9
+ export const get = query({
10
+ args: { bucketRef: v.string(), scope: v.string() },
11
+ handler: async (ctx, arguments_) => {
12
+ [arguments_.scope, arguments_.bucketRef].forEach((value) => {
13
+ if (value.length === 0 || value.length > MAX_REF_LENGTH)
14
+ fail("INVALID_REF", "refs must be 1..256 characters");
15
+ });
16
+ const bucket = await ctx.db
17
+ .query("buckets")
18
+ .withIndex("by_scope_ref", (q) => q.eq("scope", arguments_.scope).eq("bucketRef", arguments_.bucketRef))
19
+ .unique();
20
+ if (bucket === null) {
21
+ // eslint-disable-next-line unicorn/no-null -- Convex serializes null; undefined is not a valid cursor/result.
22
+ return null;
23
+ }
24
+ return {
25
+ bucketRef: bucket.bucketRef,
26
+ capacity: bucket.capacity,
27
+ closedAt: bucket.closedAt,
28
+ lockedAt: bucket.lockedAt,
29
+ memberCount: bucket.memberCount,
30
+ openedAt: bucket.openedAt,
31
+ status: bucket.status,
32
+ };
33
+ },
34
+ returns: v.union(v.null(), bucketState),
35
+ });
36
+ export const paginateMembers = query({
37
+ args: {
38
+ bucketRef: v.string(),
39
+ paginationOpts: paginationOptsValidator,
40
+ scope: v.string(),
41
+ },
42
+ handler: async (ctx, arguments_) => {
43
+ [arguments_.scope, arguments_.bucketRef].forEach((value) => {
44
+ if (value.length === 0 || value.length > MAX_REF_LENGTH)
45
+ fail("INVALID_REF", "refs must be 1..256 characters");
46
+ });
47
+ const size = arguments_.paginationOpts.numItems;
48
+ if (!Number.isSafeInteger(size) || size < 1 || size > MAX_LIST_LIMIT) {
49
+ fail("INVALID_LIMIT", `numItems must be 1..${String(MAX_LIST_LIMIT)}`);
50
+ }
51
+ const result = await ctx.db
52
+ .query("members")
53
+ .withIndex("by_bucket", (q) => q.eq("scope", arguments_.scope).eq("bucketRef", arguments_.bucketRef))
54
+ .paginate(arguments_.paginationOpts);
55
+ return {
56
+ continueCursor: result.continueCursor,
57
+ isDone: result.isDone,
58
+ page: result.page.map((member) => ({
59
+ joinedAt: member.joinedAt,
60
+ subjectRef: member.subjectRef,
61
+ })),
62
+ };
63
+ },
64
+ returns: v.object({
65
+ continueCursor: v.string(),
66
+ isDone: v.boolean(),
67
+ page: v.array(memberState),
68
+ }),
69
+ });
70
+ /** Bounded preview; use paginateMembers to list every member. */
71
+ export const listMembers = query({
72
+ args: {
73
+ bucketRef: v.string(),
74
+ limit: v.optional(v.number()),
75
+ scope: v.string(),
76
+ },
77
+ handler: async (ctx, arguments_) => {
78
+ [arguments_.scope, arguments_.bucketRef].forEach((value) => {
79
+ if (value.length === 0 || value.length > MAX_REF_LENGTH)
80
+ fail("INVALID_REF", "refs must be 1..256 characters");
81
+ });
82
+ const raw = arguments_.limit ?? DEFAULT_LIST_LIMIT;
83
+ if (!Number.isSafeInteger(raw)) {
84
+ fail("INVALID_LIMIT", "limit must be a positive integer");
85
+ }
86
+ if (raw < 1) {
87
+ fail("INVALID_LIMIT", "limit must be a positive integer");
88
+ }
89
+ const limit = Math.min(raw, MAX_LIST_LIMIT);
90
+ const members = await ctx.db
91
+ .query("members")
92
+ .withIndex("by_bucket", (q) => q.eq("scope", arguments_.scope).eq("bucketRef", arguments_.bucketRef))
93
+ .take(limit);
94
+ return members.map((member) => ({
95
+ joinedAt: member.joinedAt,
96
+ subjectRef: member.subjectRef,
97
+ }));
98
+ },
99
+ returns: v.array(memberState),
100
+ });
101
+ //# sourceMappingURL=queries.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/component/queries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE/E,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAExD,SAAS,IAAI,CAAC,IAAY,EAAE,OAAe;IACzC,MAAM,IAAI,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG,KAAK,CAAC;IACvB,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;IAClD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE;QACjC,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YACzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,cAAc;gBACrD,IAAI,CAAC,aAAa,EAAE,gCAAgC,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE;aACxB,KAAK,CAAC,SAAS,CAAC;aAChB,SAAS,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,CAC/B,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,SAAS,CAAC,CACtE;aACA,MAAM,EAAE,CAAC;QACZ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,8GAA8G;YAC9G,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC;CACxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;IACnC,IAAI,EAAE;QACJ,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,cAAc,EAAE,uBAAuB;QACvC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;KAClB;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE;QACjC,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YACzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,cAAc;gBACrD,IAAI,CAAC,aAAa,EAAE,gCAAgC,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,UAAU,CAAC,cAAc,CAAC,QAAQ,CAAC;QAChD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,cAAc,EAAE,CAAC;YACrE,IAAI,CAAC,eAAe,EAAE,uBAAuB,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE;aACxB,KAAK,CAAC,SAAS,CAAC;aAChB,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAC5B,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,SAAS,CAAC,CACtE;aACA,QAAQ,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;QACvC,OAAO;YACL,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,UAAU,EAAE,MAAM,CAAC,UAAU;aAC9B,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;QAC1B,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;QACnB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;KAC3B,CAAC;CACH,CAAC,CAAC;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,CAAC;IAC/B,IAAI,EAAE;QACJ,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAC7B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;KAClB;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE;QACjC,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YACzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,cAAc;gBACrD,IAAI,CAAC,aAAa,EAAE,gCAAgC,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC;QACH,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,IAAI,kBAAkB,CAAC;QACnD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,eAAe,EAAE,kCAAkC,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACZ,IAAI,CAAC,eAAe,EAAE,kCAAkC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,EAAE;aACzB,KAAK,CAAC,SAAS,CAAC;aAChB,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAC5B,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,SAAS,CAAC,CACtE;aACA,IAAI,CAAC,KAAK,CAAC,CAAC;QACf,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC9B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,UAAU,EAAE,MAAM,CAAC,UAAU;SAC9B,CAAC,CAAC,CAAC;IACN,CAAC;IACD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;CAC9B,CAAC,CAAC"}
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Sandboxed tables — ephemeral groups of opaque `subjectRef`s. Distinct from
3
+ * `convex-memberships` (standing org/roles) and `@convex-dev/presence` (liveness).
4
+ *
5
+ * `memberCount` lives on the bucket row so join capacity is OCC-safe: concurrent
6
+ * joins patch the same document and Convex retries the loser.
7
+ */
8
+ declare const _default: import("convex/server").SchemaDefinition<{
9
+ buckets: import("convex/server").TableDefinition<import("convex/values").VObject<{
10
+ bucketRef: string;
11
+ capacity?: number | undefined;
12
+ closedAt?: number | undefined;
13
+ lockedAt?: number | undefined;
14
+ memberCount: number;
15
+ openedAt: number;
16
+ scope: string;
17
+ status: "closed" | "locked" | "open";
18
+ }, {
19
+ bucketRef: import("convex/values").VString<string, "required">;
20
+ capacity: import("convex/values").VFloat64<number | undefined, "optional">;
21
+ closedAt: import("convex/values").VFloat64<number | undefined, "optional">;
22
+ lockedAt: import("convex/values").VFloat64<number | undefined, "optional">;
23
+ memberCount: import("convex/values").VFloat64<number, "required">;
24
+ openedAt: import("convex/values").VFloat64<number, "required">;
25
+ scope: import("convex/values").VString<string, "required">;
26
+ status: import("convex/values").VUnion<"closed" | "locked" | "open", [import("convex/values").VLiteral<"closed", "required">, import("convex/values").VLiteral<"locked", "required">, import("convex/values").VLiteral<"open", "required">], "required", never>;
27
+ }, "required", "bucketRef" | "capacity" | "closedAt" | "lockedAt" | "memberCount" | "openedAt" | "scope" | "status">, {
28
+ by_scope_ref: ["scope", "bucketRef", "_creationTime"];
29
+ }, {}, {}>;
30
+ members: import("convex/server").TableDefinition<import("convex/values").VObject<{
31
+ bucketRef: string;
32
+ joinedAt: number;
33
+ scope: string;
34
+ subjectRef: string;
35
+ }, {
36
+ bucketRef: import("convex/values").VString<string, "required">;
37
+ joinedAt: import("convex/values").VFloat64<number, "required">;
38
+ scope: import("convex/values").VString<string, "required">;
39
+ subjectRef: import("convex/values").VString<string, "required">;
40
+ }, "required", "bucketRef" | "joinedAt" | "scope" | "subjectRef">, {
41
+ by_bucket: ["scope", "bucketRef", "_creationTime"];
42
+ by_bucket_subject: ["scope", "bucketRef", "subjectRef", "_creationTime"];
43
+ by_subject: ["scope", "subjectRef", "_creationTime"];
44
+ }, {}, {}>;
45
+ }, true>;
46
+ export default _default;
47
+ //# sourceMappingURL=schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG"}
@@ -0,0 +1,31 @@
1
+ import { defineSchema, defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ /**
4
+ * Sandboxed tables — ephemeral groups of opaque `subjectRef`s. Distinct from
5
+ * `convex-memberships` (standing org/roles) and `@convex-dev/presence` (liveness).
6
+ *
7
+ * `memberCount` lives on the bucket row so join capacity is OCC-safe: concurrent
8
+ * joins patch the same document and Convex retries the loser.
9
+ */
10
+ export default defineSchema({
11
+ buckets: defineTable({
12
+ bucketRef: v.string(),
13
+ capacity: v.optional(v.number()),
14
+ closedAt: v.optional(v.number()),
15
+ lockedAt: v.optional(v.number()),
16
+ memberCount: v.number(),
17
+ openedAt: v.number(),
18
+ scope: v.string(),
19
+ status: v.union(v.literal("closed"), v.literal("locked"), v.literal("open")),
20
+ }).index("by_scope_ref", ["scope", "bucketRef"]),
21
+ members: defineTable({
22
+ bucketRef: v.string(),
23
+ joinedAt: v.number(),
24
+ scope: v.string(),
25
+ subjectRef: v.string(),
26
+ })
27
+ .index("by_bucket", ["scope", "bucketRef"])
28
+ .index("by_bucket_subject", ["scope", "bucketRef", "subjectRef"])
29
+ .index("by_subject", ["scope", "subjectRef"]),
30
+ });
31
+ //# sourceMappingURL=schema.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC;;;;;;GAMG;AACH,eAAe,YAAY,CAAC;IAC1B,OAAO,EAAE,WAAW,CAAC;QACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAChC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAChC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,CAAC,CAAC,KAAK,CACb,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EACnB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EACnB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAClB;KACF,CAAC,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAChD,OAAO,EAAE,WAAW,CAAC;QACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;KACvB,CAAC;SACC,KAAK,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;SAC1C,KAAK,CAAC,mBAAmB,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;SAChE,KAAK,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;CAChD,CAAC,CAAC"}
@@ -0,0 +1,26 @@
1
+ export declare const bucketStatus: import("convex/values").VUnion<"closed" | "locked" | "open", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"locked", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
2
+ export declare const bucketState: import("convex/values").VObject<{
3
+ bucketRef: string;
4
+ capacity?: number | undefined;
5
+ closedAt?: number | undefined;
6
+ lockedAt?: number | undefined;
7
+ memberCount: number;
8
+ openedAt: number;
9
+ status: "closed" | "locked" | "open";
10
+ }, {
11
+ bucketRef: import("convex/values").VString<string, "required">;
12
+ capacity: import("convex/values").VFloat64<number | undefined, "optional">;
13
+ closedAt: import("convex/values").VFloat64<number | undefined, "optional">;
14
+ lockedAt: import("convex/values").VFloat64<number | undefined, "optional">;
15
+ memberCount: import("convex/values").VFloat64<number, "required">;
16
+ openedAt: import("convex/values").VFloat64<number, "required">;
17
+ status: import("convex/values").VUnion<"closed" | "locked" | "open", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"locked", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
18
+ }, "required", "bucketRef" | "capacity" | "closedAt" | "lockedAt" | "memberCount" | "openedAt" | "status">;
19
+ export declare const memberState: import("convex/values").VObject<{
20
+ joinedAt: number;
21
+ subjectRef: string;
22
+ }, {
23
+ joinedAt: import("convex/values").VFloat64<number, "required">;
24
+ subjectRef: import("convex/values").VString<string, "required">;
25
+ }, "required", "joinedAt" | "subjectRef">;
26
+ //# sourceMappingURL=validators.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,yPAIxB,CAAC;AAEF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;0GAQtB,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;yCAGtB,CAAC"}
@@ -0,0 +1,16 @@
1
+ import { v } from "convex/values";
2
+ export const bucketStatus = v.union(v.literal("open"), v.literal("locked"), v.literal("closed"));
3
+ export const bucketState = v.object({
4
+ bucketRef: v.string(),
5
+ capacity: v.optional(v.number()),
6
+ closedAt: v.optional(v.number()),
7
+ lockedAt: v.optional(v.number()),
8
+ memberCount: v.number(),
9
+ openedAt: v.number(),
10
+ status: bucketStatus,
11
+ });
12
+ export const memberState = v.object({
13
+ joinedAt: v.number(),
14
+ subjectRef: v.string(),
15
+ });
16
+ //# sourceMappingURL=validators.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CACjC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EACjB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EACnB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,MAAM,EAAE,YAAY;CACrB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC"}
@@ -0,0 +1,13 @@
1
+ /** Shared constants used by both `client/` and `component/`. */
2
+ export declare const COMPONENT_NAME = "buckets";
3
+ /** Default namespace when the host does not scope a bucket. */
4
+ export declare const DEFAULT_SCOPE = "global";
5
+ export declare const MAX_REF_LENGTH = 256;
6
+ export declare const DEFAULT_ERASE_BATCH = 200;
7
+ export declare const MAX_ERASE_BATCH = 500;
8
+ export declare const DEFAULT_LIST_LIMIT = 100;
9
+ export declare const MAX_LIST_LIMIT = 500;
10
+ export type BucketStatus = "closed" | "locked" | "open";
11
+ export declare function clampEraseBatch(batch: number): number;
12
+ export declare function clampListLimit(limit: number): number;
13
+ //# sourceMappingURL=shared.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,+DAA+D;AAC/D,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKpD"}
package/dist/shared.js ADDED
@@ -0,0 +1,22 @@
1
+ /** Shared constants used by both `client/` and `component/`. */
2
+ export const COMPONENT_NAME = "buckets";
3
+ /** Default namespace when the host does not scope a bucket. */
4
+ export const DEFAULT_SCOPE = "global";
5
+ export const MAX_REF_LENGTH = 256;
6
+ export const DEFAULT_ERASE_BATCH = 200;
7
+ export const MAX_ERASE_BATCH = 500;
8
+ export const DEFAULT_LIST_LIMIT = 100;
9
+ export const MAX_LIST_LIMIT = 500;
10
+ export function clampEraseBatch(batch) {
11
+ if (!Number.isInteger(batch) || batch < 1) {
12
+ throw new Error("INVALID_BATCH: batch must be a positive integer");
13
+ }
14
+ return Math.min(batch, MAX_ERASE_BATCH);
15
+ }
16
+ export function clampListLimit(limit) {
17
+ if (!Number.isInteger(limit) || limit < 1) {
18
+ throw new Error("INVALID_LIMIT: limit must be a positive integer");
19
+ }
20
+ return Math.min(limit, MAX_LIST_LIMIT);
21
+ }
22
+ //# sourceMappingURL=shared.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC;AAExC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAC;AAEtC,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAClC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AACnC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AACtC,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAIlC,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;AACzC,CAAC"}
package/package.json ADDED
@@ -0,0 +1,87 @@
1
+ {
2
+ "name": "@vllnt/convex-buckets",
3
+ "version": "0.1.0-canary.0",
4
+ "description": "Ephemeral groups of opaque subject refs — matches, lobbies, cohorts — as a Convex component",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "packageManager": "pnpm@9.15.4",
8
+ "files": [
9
+ "dist",
10
+ "src"
11
+ ],
12
+ "exports": {
13
+ "./package.json": "./package.json",
14
+ ".": {
15
+ "types": "./dist/client/index.d.ts",
16
+ "default": "./dist/client/index.js"
17
+ },
18
+ "./test": "./src/test.ts",
19
+ "./_generated/component.js": {
20
+ "types": "./dist/component/_generated/component.d.ts"
21
+ },
22
+ "./_generated/component": {
23
+ "types": "./dist/component/_generated/component.d.ts"
24
+ },
25
+ "./convex.config": {
26
+ "types": "./dist/component/convex.config.d.ts",
27
+ "default": "./dist/component/convex.config.js"
28
+ },
29
+ "./convex.config.js": {
30
+ "types": "./dist/component/convex.config.d.ts",
31
+ "default": "./dist/component/convex.config.js"
32
+ }
33
+ },
34
+ "types": "./dist/client/index.d.ts",
35
+ "module": "./dist/client/index.js",
36
+ "scripts": {},
37
+ "peerDependencies": {
38
+ "convex": "^1.45.0"
39
+ },
40
+ "devDependencies": {
41
+ "@edge-runtime/vm": "^5.0.0",
42
+ "@types/node": "^22",
43
+ "@typescript/native": "npm:typescript@7.0.2",
44
+ "@vitest/coverage-v8": "^4.1.11",
45
+ "@vllnt/eslint-config": "2.0.0",
46
+ "@vllnt/typescript": "2.0.0",
47
+ "convex": "^1.45.0",
48
+ "convex-test": "^0.0.56",
49
+ "eslint": "^9.39.5",
50
+ "prettier": "^3.9.6",
51
+ "typescript": "npm:@typescript/typescript6@^6.0.2",
52
+ "vite": "^8.2.2",
53
+ "vitest": "^4.1.11"
54
+ },
55
+ "homepage": "https://github.com/vllnt/convex-buckets#readme",
56
+ "bugs": {
57
+ "url": "https://github.com/vllnt/convex-buckets/issues"
58
+ },
59
+ "author": {
60
+ "name": "bntvllnt",
61
+ "url": "https://bntvllnt.com"
62
+ },
63
+ "funding": {
64
+ "type": "github",
65
+ "url": "https://github.com/sponsors/bntvllnt"
66
+ },
67
+ "repository": {
68
+ "type": "git",
69
+ "url": "https://github.com/vllnt/convex-buckets"
70
+ },
71
+ "engines": {
72
+ "node": ">=20.19.0"
73
+ },
74
+ "publishConfig": {
75
+ "access": "public",
76
+ "registry": "https://registry.npmjs.org",
77
+ "tag": "canary"
78
+ },
79
+ "sideEffects": false,
80
+ "keywords": [
81
+ "convex",
82
+ "convex-component",
83
+ "buckets",
84
+ "match",
85
+ "lobby"
86
+ ]
87
+ }
@@ -0,0 +1,247 @@
1
+ import type {
2
+ FunctionArgs,
3
+ FunctionReference,
4
+ FunctionReturnType,
5
+ PaginationOptions,
6
+ PaginationResult,
7
+ } from "convex/server";
8
+
9
+ import { DEFAULT_SCOPE } from "../shared.js";
10
+
11
+ import type {
12
+ BucketsOptions,
13
+ BucketState,
14
+ JoinResult,
15
+ MemberState,
16
+ OpenOptions,
17
+ } from "./types.js";
18
+
19
+ export type BucketsComponent = {
20
+ mutations: {
21
+ close: FunctionReference<
22
+ "mutation",
23
+ "internal",
24
+ { bucketRef: string; scope: string },
25
+ boolean
26
+ >;
27
+ eraseBucket: FunctionReference<
28
+ "mutation",
29
+ "internal",
30
+ { batch?: number; bucketRef: string; scope: string },
31
+ number
32
+ >;
33
+ eraseSubject: FunctionReference<
34
+ "mutation",
35
+ "internal",
36
+ { batch?: number; scope: string; subjectRef: string },
37
+ number
38
+ >;
39
+ join: FunctionReference<
40
+ "mutation",
41
+ "internal",
42
+ { bucketRef: string; scope: string; subjectRef: string },
43
+ JoinResult
44
+ >;
45
+ leave: FunctionReference<
46
+ "mutation",
47
+ "internal",
48
+ { bucketRef: string; scope: string; subjectRef: string },
49
+ boolean
50
+ >;
51
+ lock: FunctionReference<
52
+ "mutation",
53
+ "internal",
54
+ { bucketRef: string; scope: string },
55
+ boolean
56
+ >;
57
+ open: FunctionReference<
58
+ "mutation",
59
+ "internal",
60
+ { bucketRef?: string; capacity?: number; scope: string },
61
+ string
62
+ >;
63
+ };
64
+ queries: {
65
+ get: FunctionReference<
66
+ "query",
67
+ "internal",
68
+ { bucketRef: string; scope: string },
69
+ BucketState | null
70
+ >;
71
+ listMembers: FunctionReference<
72
+ "query",
73
+ "internal",
74
+ { bucketRef: string; limit?: number; scope: string },
75
+ MemberState[]
76
+ >;
77
+ paginateMembers: FunctionReference<
78
+ "query",
79
+ "internal",
80
+ { bucketRef: string; paginationOpts: PaginationOptions; scope: string },
81
+ PaginationResult<MemberState>
82
+ >;
83
+ };
84
+ };
85
+
86
+ type RunQueryCtx = {
87
+ runQuery<TQuery extends FunctionReference<"query", "internal">>(
88
+ reference: TQuery,
89
+ arguments_: FunctionArgs<TQuery>,
90
+ ): Promise<FunctionReturnType<TQuery>>;
91
+ };
92
+
93
+ type RunMutationCtx = {
94
+ runMutation<TMutation extends FunctionReference<"mutation", "internal">>(
95
+ reference: TMutation,
96
+ arguments_: FunctionArgs<TMutation>,
97
+ ): Promise<FunctionReturnType<TMutation>>;
98
+ };
99
+
100
+ export class Buckets {
101
+ private readonly defaultScope: string;
102
+
103
+ constructor(
104
+ private readonly component: BucketsComponent,
105
+ options: BucketsOptions = {},
106
+ ) {
107
+ this.defaultScope = options.defaultScope ?? DEFAULT_SCOPE;
108
+ }
109
+
110
+ private scopeOf(scope?: string): string {
111
+ return scope ?? this.defaultScope;
112
+ }
113
+
114
+ open(ctx: RunMutationCtx, options: OpenOptions = {}): Promise<string> {
115
+ return ctx.runMutation(this.component.mutations.open, {
116
+ bucketRef: options.bucketRef,
117
+ capacity: options.capacity,
118
+ scope: this.scopeOf(options.scope),
119
+ });
120
+ }
121
+
122
+ // eslint-disable-next-line max-params -- Preserve the existing positional public API.
123
+ join(
124
+ ctx: RunMutationCtx,
125
+ bucketRef: string,
126
+ subjectRef: string,
127
+ scope?: string,
128
+ ): Promise<JoinResult> {
129
+ return ctx.runMutation(this.component.mutations.join, {
130
+ bucketRef,
131
+ scope: this.scopeOf(scope),
132
+ subjectRef,
133
+ });
134
+ }
135
+
136
+ // eslint-disable-next-line max-params -- Preserve the existing positional public API.
137
+ leave(
138
+ ctx: RunMutationCtx,
139
+ bucketRef: string,
140
+ subjectRef: string,
141
+ scope?: string,
142
+ ): Promise<boolean> {
143
+ return ctx.runMutation(this.component.mutations.leave, {
144
+ bucketRef,
145
+ scope: this.scopeOf(scope),
146
+ subjectRef,
147
+ });
148
+ }
149
+
150
+ lock(
151
+ ctx: RunMutationCtx,
152
+ bucketRef: string,
153
+ scope?: string,
154
+ ): Promise<boolean> {
155
+ return ctx.runMutation(this.component.mutations.lock, {
156
+ bucketRef,
157
+ scope: this.scopeOf(scope),
158
+ });
159
+ }
160
+
161
+ close(
162
+ ctx: RunMutationCtx,
163
+ bucketRef: string,
164
+ scope?: string,
165
+ ): Promise<boolean> {
166
+ return ctx.runMutation(this.component.mutations.close, {
167
+ bucketRef,
168
+ scope: this.scopeOf(scope),
169
+ });
170
+ }
171
+
172
+ get(
173
+ ctx: RunQueryCtx,
174
+ bucketRef: string,
175
+ scope?: string,
176
+ ): Promise<BucketState | null> {
177
+ return ctx.runQuery(this.component.queries.get, {
178
+ bucketRef,
179
+ scope: this.scopeOf(scope),
180
+ });
181
+ }
182
+
183
+ // eslint-disable-next-line max-params -- Preserve the existing positional public API.
184
+ paginateMembers(
185
+ ctx: RunQueryCtx,
186
+ bucketRef: string,
187
+ paginationOptions: PaginationOptions,
188
+ scope?: string,
189
+ ): Promise<PaginationResult<MemberState>> {
190
+ return ctx.runQuery(this.component.queries.paginateMembers, {
191
+ bucketRef,
192
+ paginationOpts: paginationOptions,
193
+ scope: this.scopeOf(scope),
194
+ });
195
+ }
196
+
197
+ // eslint-disable-next-line max-params -- Preserve the existing positional public API.
198
+ listMembers(
199
+ ctx: RunQueryCtx,
200
+ bucketRef: string,
201
+ scope?: string,
202
+ limit?: number,
203
+ ): Promise<MemberState[]> {
204
+ return ctx.runQuery(this.component.queries.listMembers, {
205
+ bucketRef,
206
+ limit,
207
+ scope: this.scopeOf(scope),
208
+ });
209
+ }
210
+
211
+ // eslint-disable-next-line max-params -- Preserve the existing positional public API.
212
+ eraseBucket(
213
+ ctx: RunMutationCtx,
214
+ bucketRef: string,
215
+ scope?: string,
216
+ batch?: number,
217
+ ): Promise<number> {
218
+ return ctx.runMutation(this.component.mutations.eraseBucket, {
219
+ batch,
220
+ bucketRef,
221
+ scope: this.scopeOf(scope),
222
+ });
223
+ }
224
+
225
+ // eslint-disable-next-line max-params -- Preserve the existing positional public API.
226
+ eraseSubject(
227
+ ctx: RunMutationCtx,
228
+ subjectRef: string,
229
+ scope?: string,
230
+ batch?: number,
231
+ ): Promise<number> {
232
+ return ctx.runMutation(this.component.mutations.eraseSubject, {
233
+ batch,
234
+ scope: this.scopeOf(scope),
235
+ subjectRef,
236
+ });
237
+ }
238
+ }
239
+
240
+ export {
241
+ type BucketsOptions,
242
+ type BucketState,
243
+ type BucketStatus,
244
+ type JoinResult,
245
+ type MemberState,
246
+ type OpenOptions,
247
+ } from "./types.js";
@@ -0,0 +1,33 @@
1
+ /** Public TypeScript surface for the buckets client. */
2
+
3
+ export type BucketStatus = "closed" | "locked" | "open";
4
+
5
+ export type BucketState = {
6
+ bucketRef: string;
7
+ capacity?: number;
8
+ closedAt?: number;
9
+ lockedAt?: number;
10
+ memberCount: number;
11
+ openedAt: number;
12
+ status: BucketStatus;
13
+ };
14
+
15
+ export type MemberState = {
16
+ joinedAt: number;
17
+ subjectRef: string;
18
+ };
19
+
20
+ export type JoinResult = {
21
+ joined: boolean;
22
+ reason?: string;
23
+ };
24
+
25
+ export type BucketsOptions = {
26
+ defaultScope?: string;
27
+ };
28
+
29
+ export type OpenOptions = {
30
+ bucketRef?: string;
31
+ capacity?: number;
32
+ scope?: string;
33
+ };