@vllnt/convex-progression 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 (73) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/LICENSE +21 -0
  3. package/README.md +144 -0
  4. package/dist/client/index.d.ts +61 -0
  5. package/dist/client/index.d.ts.map +1 -0
  6. package/dist/client/index.js +64 -0
  7. package/dist/client/index.js.map +1 -0
  8. package/dist/client/types.d.ts +20 -0
  9. package/dist/client/types.d.ts.map +1 -0
  10. package/dist/client/types.js +3 -0
  11. package/dist/client/types.js.map +1 -0
  12. package/dist/component/_generated/api.d.ts +40 -0
  13. package/dist/component/_generated/api.d.ts.map +1 -0
  14. package/dist/component/_generated/api.js +31 -0
  15. package/dist/component/_generated/api.js.map +1 -0
  16. package/dist/component/_generated/component.d.ts +82 -0
  17. package/dist/component/_generated/component.d.ts.map +1 -0
  18. package/dist/component/_generated/component.js +11 -0
  19. package/dist/component/_generated/component.js.map +1 -0
  20. package/dist/component/_generated/dataModel.d.ts +46 -0
  21. package/dist/component/_generated/dataModel.d.ts.map +1 -0
  22. package/dist/component/_generated/dataModel.js +11 -0
  23. package/dist/component/_generated/dataModel.js.map +1 -0
  24. package/dist/component/_generated/server.d.ts +133 -0
  25. package/dist/component/_generated/server.d.ts.map +1 -0
  26. package/dist/component/_generated/server.js +80 -0
  27. package/dist/component/_generated/server.js.map +1 -0
  28. package/dist/component/convex.config.d.ts +3 -0
  29. package/dist/component/convex.config.d.ts.map +1 -0
  30. package/dist/component/convex.config.js +4 -0
  31. package/dist/component/convex.config.js.map +1 -0
  32. package/dist/component/mutations.d.ts +43 -0
  33. package/dist/component/mutations.d.ts.map +1 -0
  34. package/dist/component/mutations.js +179 -0
  35. package/dist/component/mutations.js.map +1 -0
  36. package/dist/component/queries.d.ts +14 -0
  37. package/dist/component/queries.d.ts.map +1 -0
  38. package/dist/component/queries.js +45 -0
  39. package/dist/component/queries.js.map +1 -0
  40. package/dist/component/schema.d.ts +32 -0
  41. package/dist/component/schema.d.ts.map +1 -0
  42. package/dist/component/schema.js +21 -0
  43. package/dist/component/schema.js.map +1 -0
  44. package/dist/component/validation.d.ts +4 -0
  45. package/dist/component/validation.d.ts.map +1 -0
  46. package/dist/component/validation.js +22 -0
  47. package/dist/component/validation.js.map +1 -0
  48. package/dist/component/validators.d.ts +52 -0
  49. package/dist/component/validators.d.ts.map +1 -0
  50. package/dist/component/validators.js +20 -0
  51. package/dist/component/validators.js.map +1 -0
  52. package/dist/shared.d.ts +15 -0
  53. package/dist/shared.d.ts.map +1 -0
  54. package/dist/shared.js +36 -0
  55. package/dist/shared.js.map +1 -0
  56. package/docs/API.md +69 -0
  57. package/llms-full.txt +930 -0
  58. package/llms.txt +35 -0
  59. package/package.json +92 -0
  60. package/src/client/index.ts +191 -0
  61. package/src/client/types.ts +23 -0
  62. package/src/component/_generated/api.ts +56 -0
  63. package/src/component/_generated/component.ts +107 -0
  64. package/src/component/_generated/dataModel.ts +60 -0
  65. package/src/component/_generated/server.ts +169 -0
  66. package/src/component/convex.config.ts +5 -0
  67. package/src/component/mutations.ts +205 -0
  68. package/src/component/queries.ts +50 -0
  69. package/src/component/schema.ts +21 -0
  70. package/src/component/validation.ts +30 -0
  71. package/src/component/validators.ts +23 -0
  72. package/src/shared.ts +47 -0
  73. package/src/test.ts +15 -0
@@ -0,0 +1,52 @@
1
+ export declare const progressState: import("convex/values").VObject<{
2
+ lastPeriodKey?: string | undefined;
3
+ level: number;
4
+ maxStreak: number;
5
+ streak: number;
6
+ updatedAt: number;
7
+ xp: number;
8
+ }, {
9
+ lastPeriodKey: import("convex/values").VString<string | undefined, "optional">;
10
+ level: import("convex/values").VFloat64<number, "required">;
11
+ maxStreak: import("convex/values").VFloat64<number, "required">;
12
+ streak: import("convex/values").VFloat64<number, "required">;
13
+ updatedAt: import("convex/values").VFloat64<number, "required">;
14
+ xp: import("convex/values").VFloat64<number, "required">;
15
+ }, "required", "lastPeriodKey" | "level" | "maxStreak" | "streak" | "updatedAt" | "xp">;
16
+ export declare const accrueResult: import("convex/values").VObject<{
17
+ lastPeriodKey?: string | undefined;
18
+ level: number;
19
+ leveledUp: boolean;
20
+ maxStreak: number;
21
+ previousLevel: number;
22
+ streak: number;
23
+ updatedAt: number;
24
+ xp: number;
25
+ }, {
26
+ lastPeriodKey: import("convex/values").VString<string | undefined, "optional">;
27
+ level: import("convex/values").VFloat64<number, "required">;
28
+ maxStreak: import("convex/values").VFloat64<number, "required">;
29
+ streak: import("convex/values").VFloat64<number, "required">;
30
+ updatedAt: import("convex/values").VFloat64<number, "required">;
31
+ xp: import("convex/values").VFloat64<number, "required">;
32
+ leveledUp: import("convex/values").VBoolean<boolean, "required">;
33
+ previousLevel: import("convex/values").VFloat64<number, "required">;
34
+ }, "required", "lastPeriodKey" | "level" | "leveledUp" | "maxStreak" | "previousLevel" | "streak" | "updatedAt" | "xp">;
35
+ export declare const activityResult: import("convex/values").VObject<{
36
+ lastPeriodKey?: string | undefined;
37
+ level: number;
38
+ maxStreak: number;
39
+ streak: number;
40
+ streakDelta: number;
41
+ updatedAt: number;
42
+ xp: number;
43
+ }, {
44
+ lastPeriodKey: import("convex/values").VString<string | undefined, "optional">;
45
+ level: import("convex/values").VFloat64<number, "required">;
46
+ maxStreak: import("convex/values").VFloat64<number, "required">;
47
+ streak: import("convex/values").VFloat64<number, "required">;
48
+ updatedAt: import("convex/values").VFloat64<number, "required">;
49
+ xp: import("convex/values").VFloat64<number, "required">;
50
+ streakDelta: import("convex/values").VFloat64<number, "required">;
51
+ }, "required", "lastPeriodKey" | "level" | "maxStreak" | "streak" | "streakDelta" | "updatedAt" | "xp">;
52
+ //# sourceMappingURL=validators.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;uFAA2B,CAAC;AAEtD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;uHAIvB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;uGAGzB,CAAC"}
@@ -0,0 +1,20 @@
1
+ import { v } from "convex/values";
2
+ const progressFields = {
3
+ lastPeriodKey: v.optional(v.string()),
4
+ level: v.number(),
5
+ maxStreak: v.number(),
6
+ streak: v.number(),
7
+ updatedAt: v.number(),
8
+ xp: v.number(),
9
+ };
10
+ export const progressState = v.object(progressFields);
11
+ export const accrueResult = v.object({
12
+ ...progressFields,
13
+ leveledUp: v.boolean(),
14
+ previousLevel: v.number(),
15
+ });
16
+ export const activityResult = v.object({
17
+ ...progressFields,
18
+ streakDelta: v.number(),
19
+ });
20
+ //# 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,GAAG;IACrB,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACrC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;AAEtD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,GAAG,cAAc;IACjB,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;IACtB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;CAC1B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,GAAG,cAAc;IACjB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CACxB,CAAC,CAAC"}
@@ -0,0 +1,15 @@
1
+ /** Shared constants used by both `client/` and `component/`. */
2
+ export declare const COMPONENT_NAME = "progression";
3
+ /** Default namespace when the host does not scope progress. */
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
+ /**
9
+ * Level is the count of thresholds the current XP has reached.
10
+ * `thresholds` must be strictly increasing non-negative numbers.
11
+ */
12
+ export declare function levelForXp(xp: number, thresholds: readonly number[]): number;
13
+ export declare function assertThresholds(thresholds: readonly number[]): void;
14
+ export declare function clampEraseBatch(batch: number): number;
15
+ //# 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,gBAAgB,CAAC;AAE5C,+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;AAEnC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAI5E;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAkBpE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKrD"}
package/dist/shared.js ADDED
@@ -0,0 +1,36 @@
1
+ /** Shared constants used by both `client/` and `component/`. */
2
+ export const COMPONENT_NAME = "progression";
3
+ /** Default namespace when the host does not scope progress. */
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
+ /**
9
+ * Level is the count of thresholds the current XP has reached.
10
+ * `thresholds` must be strictly increasing non-negative numbers.
11
+ */
12
+ export function levelForXp(xp, thresholds) {
13
+ return thresholds.reduce((level, threshold) => {
14
+ return xp >= threshold ? level + 1 : level;
15
+ }, 0);
16
+ }
17
+ export function assertThresholds(thresholds) {
18
+ thresholds.reduce((previous, threshold) => {
19
+ if (!Number.isFinite(threshold) ||
20
+ threshold < 0 ||
21
+ threshold > Number.MAX_SAFE_INTEGER) {
22
+ throw new Error("INVALID_THRESHOLDS: thresholds must be finite and in 0..MAX_SAFE_INTEGER");
23
+ }
24
+ if (threshold <= previous) {
25
+ throw new Error("INVALID_THRESHOLDS: thresholds must be strictly increasing");
26
+ }
27
+ return threshold;
28
+ }, -1);
29
+ }
30
+ export function clampEraseBatch(batch) {
31
+ if (!Number.isInteger(batch) || batch < 1) {
32
+ throw new Error("INVALID_BATCH: batch must be a positive integer");
33
+ }
34
+ return Math.min(batch, MAX_ERASE_BATCH);
35
+ }
36
+ //# 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,aAAa,CAAC;AAE5C,+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;AAEnC;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU,EAAE,UAA6B;IAClE,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;QAC5C,OAAO,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7C,CAAC,EAAE,CAAC,CAAC,CAAC;AACR,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,UAA6B;IAC5D,UAAU,CAAC,MAAM,CAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE;QAChD,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;YAC3B,SAAS,GAAG,CAAC;YACb,SAAS,GAAG,MAAM,CAAC,gBAAgB,EACnC,CAAC;YACD,MAAM,IAAI,KAAK,CACb,0EAA0E,CAC3E,CAAC;QACJ,CAAC;QACD,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACT,CAAC;AAED,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"}
package/docs/API.md ADDED
@@ -0,0 +1,69 @@
1
+ # API Reference — @vllnt/convex-progression
2
+
3
+ **Compatibility:** `convex@^1.45.0`
4
+
5
+ ```ts
6
+ import { Progression } from "@vllnt/convex-progression";
7
+
8
+ const xp = new Progression(components.progression, { defaultScope: "global" });
9
+ ```
10
+
11
+ `subjectRef`, `key`, `scope`, `periodKey`, and provided `expectedPrevious` are
12
+ opaque host strings (1..256 UTF-16 code units). Never trust these, `delta`, or
13
+ `thresholds` from an end-user without host authorization. `thresholds` must be
14
+ strictly increasing, finite, and in `0..Number.MAX_SAFE_INTEGER` (empty is valid).
15
+ These rules apply to reads as well as writes, including missing-row queries.
16
+
17
+ ### `accrue(ctx, subjectRef, key, delta, thresholds, scope?)`
18
+
19
+ Adds `delta` XP (positive finite, at most `Number.MAX_SAFE_INTEGER`). Fractions
20
+ are supported with JavaScript floating-point rounding. Rejects totals above that
21
+ bound or an addition that makes no progress (`XP_OVERFLOW`). `level` counts
22
+ reached thresholds. `previousLevel` is the stored level from the previous write;
23
+ `leveledUp` compares against it, so a changed ladder can itself produce a level-up.
24
+
25
+ ### `recordActivity(ctx, subjectRef, key, periodKey, thresholds, opts?)`
26
+
27
+ `opts`: `{ scope?, expectedPrevious? }`.
28
+
29
+ - Same `periodKey` as stored → streak unchanged (`streakDelta: 0`), but level
30
+ is recomputed and `updatedAt` is refreshed.
31
+ - `lastPeriodKey === expectedPrevious` → streak + 1.
32
+ - Otherwise → streak resets to 1.
33
+
34
+ ### `get(ctx, subjectRef, key, scope?, thresholds?)`
35
+
36
+ Returns the progress row or `null`. When `thresholds` is passed, `level` is
37
+ recomputed from stored XP.
38
+
39
+ ### `reset(ctx, subjectRef, key, scope?)`
40
+
41
+ Deletes that `(scope, subjectRef, key)` row.
42
+
43
+ ### `eraseSubject(ctx, subjectRef, scope?, batch?)`
44
+
45
+ Deletes up to `batch` rows (default 200, positive integer clamped to 500),
46
+ returning only this pass's count. A full batch atomically schedules another pass;
47
+ there is no completion token or aggregate count.
48
+
49
+ ### Lifecycle and retries
50
+
51
+ - `accrue` is additive, **not event-idempotent**. Host mutations should deduplicate
52
+ event IDs atomically with awards. Convex transaction retries are distinct from
53
+ submitting a new logical award request.
54
+ - Periods are opaque, not ordered. Only the latest period is remembered. Replaying
55
+ an older period can reset/rewind a streak; the host must reject stale events and
56
+ serialize its period policy. `expectedPrevious` declares adjacency, not a CAS
57
+ precondition. Streaks exceeding `MAX_SAFE_INTEGER` reject with `STREAK_OVERFLOW`.
58
+ - Erase has no tombstone or write fence. Gate writes before starting erasure and
59
+ keep them gated until a host-controlled completion check. Concurrent/new writes
60
+ may be deleted by scheduled passes or survive after the final pass. Reset does
61
+ not cancel pending subject erasure. Schedule execution failures require host
62
+ monitoring and retry; this component has no durable completion status.
63
+ - `get` with thresholds only recomputes the returned level; it does not persist
64
+ the ladder or level. Threshold policy consistency belongs to the host.
65
+
66
+ Validation failures use `ConvexError` data `{ code, message }`: `INVALID_REF`,
67
+ `INVALID_THRESHOLDS`, `INVALID_DELTA`, `INVALID_BATCH`, `XP_OVERFLOW`, or
68
+ `STREAK_OVERFLOW`. There are no component logs; hosts should monitor rejected
69
+ calls and scheduled-function failures without logging sensitive refs.