Skip to content

Commit f5bbb48

Browse files
committed
SDK readme
1 parent 41c5f86 commit f5bbb48

1 file changed

Lines changed: 190 additions & 0 deletions

File tree

‎packages/sdk/README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# voidflag
2+
3+
The official TypeScript SDK for [VoidFlag](https://voidflag.vercel.app/), a schema-first feature flag and remote config platform with end-to-end type safety.
4+
5+
## Installation
6+
7+
```bash
8+
npm install voidflag
9+
# or
10+
pnpm add voidflag
11+
```
12+
13+
> **Node < 22**: EventSource is not built in. Install the polyfill:
14+
>
15+
> ```bash
16+
> npm install eventsource
17+
> ```
18+
19+
---
20+
21+
## Quick Start
22+
23+
The SDK is generated for you by the CLI (`vf generate`), which produces a typed client from your `schema.vf` file. You typically won't construct `VoidClient` manually, but if you need to, here's the shape:
24+
25+
```ts
26+
import { VoidClient } from 'voidflag';
27+
28+
const client = new VoidClient({
29+
envKey: 'your-env-key',
30+
schema: {
31+
darkMode: { type: 'BOOLEAN', fallback: false },
32+
theme: { type: 'STRING', fallback: 'light' },
33+
maxItems: { type: 'NUMBER', fallback: 10 },
34+
},
35+
});
36+
37+
// Access flags
38+
client.flags.darkMode.value; // boolean
39+
client.flags.theme.value; // string
40+
client.flags.maxItems.value; // number
41+
client.flags.darkMode.enabled; // boolean
42+
```
43+
44+
---
45+
46+
## Local Development
47+
48+
In local dev, use `dev: true` instead of an `envKey`. The SDK will connect to the local dev server started by `vf dev`:
49+
50+
```ts
51+
const client = new VoidClient({
52+
dev: true,
53+
schema: { ... },
54+
});
55+
```
56+
57+
If the dev server isn't running, the SDK falls back to schema defaults and retries silently in the background.
58+
59+
---
60+
61+
## Flag Access
62+
63+
Flags are accessed via `client.flags.<name>`, O(1) property lookups backed by an accessor cache.
64+
65+
```ts
66+
const flag = client.flags.darkMode;
67+
68+
flag.value; // The current value, or fallback if the flag is disabled
69+
flag.enabled; // Whether the flag is active
70+
```
71+
72+
### Rollout / Gradual Releases
73+
74+
Check whether a specific user is included in a percentage rollout:
75+
76+
```ts
77+
if (client.flags.darkMode.isRolledOutFor(userId)) {
78+
// user is in the rollout bucket
79+
}
80+
```
81+
82+
Rollout buckets are determined by a stable djb2 hash of `flagName:userId`, the same user always lands in the same bucket, with no server-side calls required.
83+
84+
---
85+
86+
## Snapshots
87+
88+
Get a point-in-time snapshot of a flag's full state:
89+
90+
```ts
91+
const snap = client.snapshot('darkMode');
92+
// { value, fallback, enabled, rollout }
93+
```
94+
95+
Get snapshots of all flags at once (useful for debugging):
96+
97+
```ts
98+
const all = client.debugSnapshots();
99+
```
100+
101+
---
102+
103+
## Overriding State (Testing)
104+
105+
Use `applyState` to override flag values locally, useful in tests or Storybook:
106+
107+
```ts
108+
client.applyState({
109+
darkMode: { value: true, enabled: true },
110+
maxItems: { value: 50 },
111+
});
112+
```
113+
114+
`applyState` is type-safe: you can only set fields that match the flag's declared type.
115+
116+
---
117+
118+
## Lifecycle Callbacks
119+
120+
```ts
121+
const client = new VoidClient({
122+
envKey: 'your-env-key',
123+
schema: { ... },
124+
125+
onConnect: () => console.log('connected'),
126+
onDisconnect: () => console.log('connection lost'),
127+
onError: (err, attempt) => console.error(`error on attempt ${attempt}`, err),
128+
onFallback: () => console.warn('SSE failed, switched to polling'),
129+
});
130+
```
131+
132+
---
133+
134+
## Transport
135+
136+
The backend determines the transport based on your plan:
137+
138+
| Plan | Transport |
139+
| ---- | -------------------------------------------- |
140+
| Free | HTTP Polling (10s interval) |
141+
| Paid | Server-Sent Events (real-time) (coming soon) |
142+
143+
If SSE fails repeatedly, the SDK automatically falls back to polling with exponential backoff (full-jitter, capped at 30s). A background probe will attempt to restore SSE when connectivity recovers.
144+
145+
---
146+
147+
## Disposing
148+
149+
Call `dispose()` when you're done with the client to stop all transports and timers:
150+
151+
```ts
152+
client.dispose();
153+
```
154+
155+
Accessing flags after disposal throws a `VoidFlagError`.
156+
157+
---
158+
159+
## Utility
160+
161+
Check if multiple flags are all enabled:
162+
163+
```ts
164+
const { flags } = client;
165+
if (client.allEnabled(flags.darkMode, flags.newDashboard)) {
166+
// both flags are on
167+
}
168+
```
169+
170+
---
171+
172+
## Error Handling
173+
174+
All errors thrown by the SDK are instances of `VoidFlagError`. Import it if you need to catch specifically:
175+
176+
```ts
177+
import { VoidFlagError } from 'voidflag';
178+
179+
try {
180+
client.snapshot('nonExistentFlag');
181+
} catch (err) {
182+
if (err instanceof VoidFlagError) { ... }
183+
}
184+
```
185+
186+
---
187+
188+
## License
189+
190+
MIT

0 commit comments

Comments
 (0)