|
| 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