@railflag/sdk-node 0.1.0 → 0.2.1

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.
package/README.md CHANGED
@@ -15,7 +15,7 @@ import { RailflagProvider } from '@railflag/sdk-node';
15
15
 
16
16
  await OpenFeature.setProviderAndWait(new RailflagProvider({
17
17
  sdkKey: process.env.RAILFLAG_SERVER_KEY!, // a server key: Environments → keys
18
- baseUrl: 'https://relay-production-aa5b.up.railway.app', // required: your Railflag relay
18
+ baseUrl: 'https://relay.railflag.com', // required: your Railflag relay
19
19
  }));
20
20
  const client = OpenFeature.getClient();
21
21
 
package/dist/index.cjs CHANGED
@@ -104,14 +104,31 @@ var clause = import_zod.z.object({
104
104
  negate: import_zod.z.boolean().optional()
105
105
  });
106
106
  var bucketing = import_zod.z.object({
107
- algorithm: import_zod.z.enum(["murmur3", "abtasty"]),
108
- /** abtasty: the variation group id that seeds the hash. */
109
- seed: import_zod.z.string().optional()
107
+ algorithm: import_zod.z.enum(["murmur3", "abtasty", "unleash", "unleash-variant"]),
108
+ /** abtasty: the variation group id that seeds the hash. unleash, unleash-variant: the strategy's groupId. */
109
+ seed: import_zod.z.string().optional(),
110
+ /**
111
+ * unleash-variant: the total variant weight Unleash takes the hash modulo (usually 1000). Unleash bucket x maps
112
+ * to floor(x * WEIGHT_SCALE / modulus), so cumulative boundaries at floor(C * WEIGHT_SCALE / modulus) are exact.
113
+ */
114
+ modulus: import_zod.z.number().int().positive().max(WEIGHT_SCALE).optional()
110
115
  });
111
116
  var rollout = import_zod.z.object({
112
117
  bucketBy: import_zod.z.string().optional(),
113
118
  weights: import_zod.z.array(import_zod.z.number().int().min(0).max(WEIGHT_SCALE)).min(1),
114
- bucketing: bucketing.optional()
119
+ bucketing: bucketing.optional(),
120
+ /** Variation indexes in the order their ranges are laid out (default: index order). Vendors such as Unleash walk their own order. */
121
+ order: import_zod.z.array(import_zod.z.number().int().min(0)).optional(),
122
+ /**
123
+ * Traffic allocation before the split, hashed separately: only users whose gate bucket is below
124
+ * `weight` get a variation; the rest continue to the next rule. Reproduces vendors that hash twice
125
+ * (Unleash rollout + variants, Split traffic allocation, DevCycle rollout).
126
+ */
127
+ gate: import_zod.z.object({
128
+ weight: import_zod.z.number().int().min(0).max(WEIGHT_SCALE),
129
+ bucketBy: import_zod.z.string().optional(),
130
+ bucketing: bucketing.optional()
131
+ }).optional()
115
132
  }).refine((r) => r.weights.reduce((a, b) => a + b, 0) <= WEIGHT_SCALE, {
116
133
  message: `Weights must add up to at most ${WEIGHT_SCALE}`
117
134
  });
@@ -165,18 +182,26 @@ var snapshot = import_zod.z.object({
165
182
  var evalReason = import_zod.z.enum(["STATIC", "DEFAULT", "TARGETING_MATCH", "SPLIT", "DISABLED", "ERROR"]);
166
183
 
167
184
  // ../eval/src/bucket.ts
185
+ var UNLEASH_VARIANT_SEED = 86028157;
168
186
  function bucketFor(flagKey2, salt, value, bucketing2) {
169
187
  if (bucketing2?.algorithm === "abtasty") {
170
188
  const seed = bucketing2.seed ?? "";
171
189
  return murmur3Latin1(seed + value) % 100 * (WEIGHT_SCALE / 100);
172
190
  }
191
+ if (bucketing2?.algorithm === "unleash") {
192
+ return murmur3Latin1(`${bucketing2.seed ?? flagKey2}:${value}`, 0) % 100 * (WEIGHT_SCALE / 100);
193
+ }
194
+ if (bucketing2?.algorithm === "unleash-variant") {
195
+ const m = bucketing2.modulus ?? 1e3;
196
+ return Math.floor(murmur3Latin1(`${bucketing2.seed ?? flagKey2}:${value}`, UNLEASH_VARIANT_SEED) % m * WEIGHT_SCALE / m);
197
+ }
173
198
  const h = murmur3(`${flagKey2}.${salt}.${value}`);
174
199
  return Math.floor(h / 4294967296 * WEIGHT_SCALE);
175
200
  }
176
- function pickWeighted(weights, bucket) {
201
+ function pickWeighted(weights, bucket, order) {
177
202
  let total = 0;
178
- for (let i = 0; i < weights.length; i++) {
179
- total += weights[i];
203
+ for (const i of order ?? weights.keys()) {
204
+ total += weights[i] ?? 0;
180
205
  if (bucket < total) return i;
181
206
  }
182
207
  return null;
@@ -310,9 +335,16 @@ function typeOf(v) {
310
335
  function resolveServe(flag, s, ctx, ruleId) {
311
336
  if ("variation" in s) return { index: s.variation, reason: ruleId ? "TARGETING_MATCH" : "DEFAULT", ruleId };
312
337
  const attr = s.rollout.bucketBy ?? "key";
338
+ const gate = s.rollout.gate;
339
+ if (gate) {
340
+ const gateAttr = gate.bucketBy ?? attr;
341
+ const g = gateAttr === "key" ? contextKeyOf(ctx) : ctx[gateAttr];
342
+ const gateBucket = g === void 0 || g === null ? 0 : bucketFor(flag.key, flag.salt, String(g), gate.bucketing);
343
+ if (gateBucket >= gate.weight) return null;
344
+ }
313
345
  const raw = attr === "key" ? contextKeyOf(ctx) : ctx[attr];
314
346
  const bucket = raw === void 0 || raw === null ? 0 : bucketFor(flag.key, flag.salt, String(raw), s.rollout.bucketing);
315
- const index = pickWeighted(s.rollout.weights, bucket);
347
+ const index = pickWeighted(s.rollout.weights, bucket, s.rollout.order);
316
348
  if (index === null) return null;
317
349
  return { index, reason: "SPLIT", ruleId };
318
350
  }
package/dist/index.d.cts CHANGED
@@ -18,8 +18,26 @@ declare const snapshot: z.ZodObject<{
18
18
  algorithm: z.ZodEnum<{
19
19
  murmur3: "murmur3";
20
20
  abtasty: "abtasty";
21
+ unleash: "unleash";
22
+ "unleash-variant": "unleash-variant";
21
23
  }>;
22
24
  seed: z.ZodOptional<z.ZodString>;
25
+ modulus: z.ZodOptional<z.ZodNumber>;
26
+ }, z.core.$strip>>;
27
+ order: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
28
+ gate: z.ZodOptional<z.ZodObject<{
29
+ weight: z.ZodNumber;
30
+ bucketBy: z.ZodOptional<z.ZodString>;
31
+ bucketing: z.ZodOptional<z.ZodObject<{
32
+ algorithm: z.ZodEnum<{
33
+ murmur3: "murmur3";
34
+ abtasty: "abtasty";
35
+ unleash: "unleash";
36
+ "unleash-variant": "unleash-variant";
37
+ }>;
38
+ seed: z.ZodOptional<z.ZodString>;
39
+ modulus: z.ZodOptional<z.ZodNumber>;
40
+ }, z.core.$strip>>;
23
41
  }, z.core.$strip>>;
24
42
  }, z.core.$strip>;
25
43
  }, z.core.$strip>]>;
@@ -63,8 +81,26 @@ declare const snapshot: z.ZodObject<{
63
81
  algorithm: z.ZodEnum<{
64
82
  murmur3: "murmur3";
65
83
  abtasty: "abtasty";
84
+ unleash: "unleash";
85
+ "unleash-variant": "unleash-variant";
66
86
  }>;
67
87
  seed: z.ZodOptional<z.ZodString>;
88
+ modulus: z.ZodOptional<z.ZodNumber>;
89
+ }, z.core.$strip>>;
90
+ order: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
91
+ gate: z.ZodOptional<z.ZodObject<{
92
+ weight: z.ZodNumber;
93
+ bucketBy: z.ZodOptional<z.ZodString>;
94
+ bucketing: z.ZodOptional<z.ZodObject<{
95
+ algorithm: z.ZodEnum<{
96
+ murmur3: "murmur3";
97
+ abtasty: "abtasty";
98
+ unleash: "unleash";
99
+ "unleash-variant": "unleash-variant";
100
+ }>;
101
+ seed: z.ZodOptional<z.ZodString>;
102
+ modulus: z.ZodOptional<z.ZodNumber>;
103
+ }, z.core.$strip>>;
68
104
  }, z.core.$strip>>;
69
105
  }, z.core.$strip>;
70
106
  }, z.core.$strip>]>;
@@ -118,7 +154,7 @@ type Snapshot = z.infer<typeof snapshot>;
118
154
 
119
155
  interface SourceOptions {
120
156
  sdkKey: string;
121
- /** Your Railflag relay, like https://relay.example.com. Required: there is no default host. */
157
+ /** Your Railflag relay: https://relay.railflag.com. Required: there is no default host. */
122
158
  baseUrl: string;
123
159
  /** Stream updates over SSE (default true). Polling still runs as a safety net. */
124
160
  stream?: boolean;
package/dist/index.d.ts CHANGED
@@ -18,8 +18,26 @@ declare const snapshot: z.ZodObject<{
18
18
  algorithm: z.ZodEnum<{
19
19
  murmur3: "murmur3";
20
20
  abtasty: "abtasty";
21
+ unleash: "unleash";
22
+ "unleash-variant": "unleash-variant";
21
23
  }>;
22
24
  seed: z.ZodOptional<z.ZodString>;
25
+ modulus: z.ZodOptional<z.ZodNumber>;
26
+ }, z.core.$strip>>;
27
+ order: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
28
+ gate: z.ZodOptional<z.ZodObject<{
29
+ weight: z.ZodNumber;
30
+ bucketBy: z.ZodOptional<z.ZodString>;
31
+ bucketing: z.ZodOptional<z.ZodObject<{
32
+ algorithm: z.ZodEnum<{
33
+ murmur3: "murmur3";
34
+ abtasty: "abtasty";
35
+ unleash: "unleash";
36
+ "unleash-variant": "unleash-variant";
37
+ }>;
38
+ seed: z.ZodOptional<z.ZodString>;
39
+ modulus: z.ZodOptional<z.ZodNumber>;
40
+ }, z.core.$strip>>;
23
41
  }, z.core.$strip>>;
24
42
  }, z.core.$strip>;
25
43
  }, z.core.$strip>]>;
@@ -63,8 +81,26 @@ declare const snapshot: z.ZodObject<{
63
81
  algorithm: z.ZodEnum<{
64
82
  murmur3: "murmur3";
65
83
  abtasty: "abtasty";
84
+ unleash: "unleash";
85
+ "unleash-variant": "unleash-variant";
66
86
  }>;
67
87
  seed: z.ZodOptional<z.ZodString>;
88
+ modulus: z.ZodOptional<z.ZodNumber>;
89
+ }, z.core.$strip>>;
90
+ order: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
91
+ gate: z.ZodOptional<z.ZodObject<{
92
+ weight: z.ZodNumber;
93
+ bucketBy: z.ZodOptional<z.ZodString>;
94
+ bucketing: z.ZodOptional<z.ZodObject<{
95
+ algorithm: z.ZodEnum<{
96
+ murmur3: "murmur3";
97
+ abtasty: "abtasty";
98
+ unleash: "unleash";
99
+ "unleash-variant": "unleash-variant";
100
+ }>;
101
+ seed: z.ZodOptional<z.ZodString>;
102
+ modulus: z.ZodOptional<z.ZodNumber>;
103
+ }, z.core.$strip>>;
68
104
  }, z.core.$strip>>;
69
105
  }, z.core.$strip>;
70
106
  }, z.core.$strip>]>;
@@ -118,7 +154,7 @@ type Snapshot = z.infer<typeof snapshot>;
118
154
 
119
155
  interface SourceOptions {
120
156
  sdkKey: string;
121
- /** Your Railflag relay, like https://relay.example.com. Required: there is no default host. */
157
+ /** Your Railflag relay: https://relay.railflag.com. Required: there is no default host. */
122
158
  baseUrl: string;
123
159
  /** Stream updates over SSE (default true). Polling still runs as a safety net. */
124
160
  stream?: boolean;
package/dist/index.js CHANGED
@@ -84,14 +84,31 @@ var clause = z.object({
84
84
  negate: z.boolean().optional()
85
85
  });
86
86
  var bucketing = z.object({
87
- algorithm: z.enum(["murmur3", "abtasty"]),
88
- /** abtasty: the variation group id that seeds the hash. */
89
- seed: z.string().optional()
87
+ algorithm: z.enum(["murmur3", "abtasty", "unleash", "unleash-variant"]),
88
+ /** abtasty: the variation group id that seeds the hash. unleash, unleash-variant: the strategy's groupId. */
89
+ seed: z.string().optional(),
90
+ /**
91
+ * unleash-variant: the total variant weight Unleash takes the hash modulo (usually 1000). Unleash bucket x maps
92
+ * to floor(x * WEIGHT_SCALE / modulus), so cumulative boundaries at floor(C * WEIGHT_SCALE / modulus) are exact.
93
+ */
94
+ modulus: z.number().int().positive().max(WEIGHT_SCALE).optional()
90
95
  });
91
96
  var rollout = z.object({
92
97
  bucketBy: z.string().optional(),
93
98
  weights: z.array(z.number().int().min(0).max(WEIGHT_SCALE)).min(1),
94
- bucketing: bucketing.optional()
99
+ bucketing: bucketing.optional(),
100
+ /** Variation indexes in the order their ranges are laid out (default: index order). Vendors such as Unleash walk their own order. */
101
+ order: z.array(z.number().int().min(0)).optional(),
102
+ /**
103
+ * Traffic allocation before the split, hashed separately: only users whose gate bucket is below
104
+ * `weight` get a variation; the rest continue to the next rule. Reproduces vendors that hash twice
105
+ * (Unleash rollout + variants, Split traffic allocation, DevCycle rollout).
106
+ */
107
+ gate: z.object({
108
+ weight: z.number().int().min(0).max(WEIGHT_SCALE),
109
+ bucketBy: z.string().optional(),
110
+ bucketing: bucketing.optional()
111
+ }).optional()
95
112
  }).refine((r) => r.weights.reduce((a, b) => a + b, 0) <= WEIGHT_SCALE, {
96
113
  message: `Weights must add up to at most ${WEIGHT_SCALE}`
97
114
  });
@@ -145,18 +162,26 @@ var snapshot = z.object({
145
162
  var evalReason = z.enum(["STATIC", "DEFAULT", "TARGETING_MATCH", "SPLIT", "DISABLED", "ERROR"]);
146
163
 
147
164
  // ../eval/src/bucket.ts
165
+ var UNLEASH_VARIANT_SEED = 86028157;
148
166
  function bucketFor(flagKey2, salt, value, bucketing2) {
149
167
  if (bucketing2?.algorithm === "abtasty") {
150
168
  const seed = bucketing2.seed ?? "";
151
169
  return murmur3Latin1(seed + value) % 100 * (WEIGHT_SCALE / 100);
152
170
  }
171
+ if (bucketing2?.algorithm === "unleash") {
172
+ return murmur3Latin1(`${bucketing2.seed ?? flagKey2}:${value}`, 0) % 100 * (WEIGHT_SCALE / 100);
173
+ }
174
+ if (bucketing2?.algorithm === "unleash-variant") {
175
+ const m = bucketing2.modulus ?? 1e3;
176
+ return Math.floor(murmur3Latin1(`${bucketing2.seed ?? flagKey2}:${value}`, UNLEASH_VARIANT_SEED) % m * WEIGHT_SCALE / m);
177
+ }
153
178
  const h = murmur3(`${flagKey2}.${salt}.${value}`);
154
179
  return Math.floor(h / 4294967296 * WEIGHT_SCALE);
155
180
  }
156
- function pickWeighted(weights, bucket) {
181
+ function pickWeighted(weights, bucket, order) {
157
182
  let total = 0;
158
- for (let i = 0; i < weights.length; i++) {
159
- total += weights[i];
183
+ for (const i of order ?? weights.keys()) {
184
+ total += weights[i] ?? 0;
160
185
  if (bucket < total) return i;
161
186
  }
162
187
  return null;
@@ -290,9 +315,16 @@ function typeOf(v) {
290
315
  function resolveServe(flag, s, ctx, ruleId) {
291
316
  if ("variation" in s) return { index: s.variation, reason: ruleId ? "TARGETING_MATCH" : "DEFAULT", ruleId };
292
317
  const attr = s.rollout.bucketBy ?? "key";
318
+ const gate = s.rollout.gate;
319
+ if (gate) {
320
+ const gateAttr = gate.bucketBy ?? attr;
321
+ const g = gateAttr === "key" ? contextKeyOf(ctx) : ctx[gateAttr];
322
+ const gateBucket = g === void 0 || g === null ? 0 : bucketFor(flag.key, flag.salt, String(g), gate.bucketing);
323
+ if (gateBucket >= gate.weight) return null;
324
+ }
293
325
  const raw = attr === "key" ? contextKeyOf(ctx) : ctx[attr];
294
326
  const bucket = raw === void 0 || raw === null ? 0 : bucketFor(flag.key, flag.salt, String(raw), s.rollout.bucketing);
295
- const index = pickWeighted(s.rollout.weights, bucket);
327
+ const index = pickWeighted(s.rollout.weights, bucket, s.rollout.order);
296
328
  if (index === null) return null;
297
329
  return { index, reason: "SPLIT", ruleId };
298
330
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@railflag/sdk-node",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "Railflag OpenFeature provider for Node.js: local evaluation, streaming updates",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -38,8 +38,8 @@
38
38
  "ioredis": "5.11.1",
39
39
  "tsup": "8.5.0",
40
40
  "@railflag/api": "0.1.0",
41
- "@railflag/relay": "0.1.0",
42
41
  "@railflag/eval": "0.1.0",
42
+ "@railflag/relay": "0.1.0",
43
43
  "@railflag/schema": "0.1.0"
44
44
  },
45
45
  "engines": {