Skip to content

Commit 41c5f86

Browse files
committed
SDK final polish before publish
generation fix according to adjust packages names
1 parent 4716d34 commit 41c5f86

19 files changed

Lines changed: 1321 additions & 56 deletions

‎PROJECT_OVERVIEW.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# VoidFlag: Project Overview
2+
3+
## 1. Overview
4+
5+
VoidFlag is a schema-first feature flag and remote configuration management system. Designed to replace stringly-typed and error-prone feature toggles, VoidFlag introduces a custom `.vf` schema language to rigorously define flags, their data types, and fallback values.
6+
7+
The core problem VoidFlag solves is the lack of type-safety, poor developer experience, and tedious local-testing loops inherent in many feature flag platforms. By pairing a robust schema definition with automatic code generation (SDK clients), local dev-servers, and varying transport strategies, VoidFlag offers a GitOps-friendly, local-first workflow that scales up to a full production system.
8+
9+
## 2. Architecture
10+
11+
VoidFlag is structured as a Turborepo monorepo with multiple distinct packages and applications:
12+
13+
- **Backend (`apps/api`)**: A NestJS application handling core business logic, user auth, project/environment management, and flag distribution.
14+
- **Frontend (`apps/frontend`)**: A Next.js application serving as the dashboard for developers to manage flags and environments.
15+
- **Developer CLI (`packages/CLI`)**: A toolset for local development (dev server), schema parsing, and client generation.
16+
- **SDK (`packages/sdk`)**: A strictly-typed TypeScript client consumed by end-user applications.
17+
- **AST Parser (`packages/parser`)**: The lexer and parser for `.vf` schema files.
18+
- **VS Code Extension (`packages/vscode-extension`)**: Syntax highlighting and IDE support for `.vf` files.
19+
20+
**Data Flow**
21+
22+
1. Developers define flags in a `schema.vf` file.
23+
2. The CLI generates a strongly-typed TypeScript client representing that specific schema.
24+
3. In local development, the CLI spins up a Dev Server, capturing API requests from the SDK and streaming flag updates via Server-Sent Events (SSE).
25+
4. In production, the schema is pushed to the central Backend. The SDK connects to the backend, which determines the optimal transport mechanism (Polling vs. SSE) based on connection stability and the user's billing plan.
26+
27+
## 3. Components Breakdown
28+
29+
### Backend (`apps/api`)
30+
31+
- **Purpose**: Centralized source of truth for projects, user environments, and feature flag states.
32+
- **Key Responsibilities**: Rate-limiting (via NestJS Throttler), authentication (JWT/OAuth2), schema syncing (validating pushed `.vf` schemas), and streaming flag states to connected clients.
33+
- **Notable Implementation**: The `/connect` endpoint inspects the `userPlan`. Users on the `FREE` tier are restricted to a `polling` transport mechanism, while paid tiers receive a persistent `sse` stream.
34+
35+
### Frontend (`apps/frontend`)
36+
37+
- **Purpose**: Developer dashboard.
38+
- **Key Responsibilities**: Visualizing flag states, managing environments, and modifying properties like rollout percentages.
39+
- **Notable Implementation**: Built on Next.js 16, utilizing modern React hooks, Zustand for local state management, TailwindCSS v4, and shadcn/ui components.
40+
41+
### Developer CLI (`packages/CLI`)
42+
43+
- **Purpose**: The bridge between the platform and the developer's local environment.
44+
- **Commands**:
45+
- `vf generate`: Reads `schema.vf`, parses the AST, and generates heavily typed `voidflag.client.ts` code for the developer's app.
46+
- `vf dev`: Starts an Express-based local dev server, injecting itself in place of the production backend. It exposes a minimal local UI to toggle flags during local development.
47+
- `vf apply`: Pushes local flag states/schemas up to the backend server.
48+
49+
### SDK (`packages/sdk`)
50+
51+
- **Purpose**: The runtime library integrated into user applications.
52+
- **Modules/Files**: `sdk.ts`, `transport.ts`.
53+
- **Implementation**: Utilizes djb2 hashing for stable user rollout allocations. Employs lazy-evaluation via an accessor cache `Object.defineProperty` for optimal read performance.
54+
55+
## 4. SDK Design
56+
57+
- **Access Patterns**: The SDK converts schema definitions into `Accessor` nodes. This forces O(1) property lookups (e.g., `vf.flags.darkMode.value`) instead of method calls (`vf.get('darkMode')`), which is cleaner and highly cacheable.
58+
- **Transport Mechanisms**:
59+
- **SSE (`SSETransport`)**: Primary real-time mechanism using `EventSource`. Resolves stream updates incrementally using patches.
60+
- **Polling (`PollingTransport`)**: Standard HTTP polling mechanism.
61+
- **Resilience & Backoff**: Features a full-jitter exponential backoff algorithm to prevent "thundering herd" scenarios when clients reconnect. If the SSE stream repeatedly fails, the SDK permanently degrades into the Polling transport.
62+
- **Typing Strategy**: Generics-heavy (`VoidClient<S extends FlagMap>`). Extracting types strictly ensures that developers cannot query flags that do not exist or expect an incorrect return type (e.g., expecting a `number` from a `boolean` flag).
63+
64+
## 5. CLI (`packages/CLI`)
65+
66+
- **Workflows Enabled**: Local-first development. The local Dev Server runs completely offline, overriding the SDK's remote endpoints. Developers can test complex feature rollouts on `localhost` without touching a staging server.
67+
- **Codegen**: Central to the UX, the CLI analyzes standard definitions and continuously overwrites a local stub, ensuring zero-latency typescript autocompletion.
68+
69+
## 6. Custom Schema / File System
70+
71+
- **The `.vf` Format**: A declarative DSL (Domain Specific Language) dedicated solely to feature flags.
72+
```vf
73+
flag darkMode {
74+
type bool
75+
fallback false
76+
}
77+
```
78+
- **Parser & Lexer**: A hand-written lexer/parser (`packages/parser`). It iterates over strings, tokenizes constraints (`flag`, `type`, `fallback`), and generates a `SchemaAST`. By owning the grammar, VoidFlag avoids JSON limitations (like lack of comments) and YAML complexities.
79+
80+
## 7. Tooling & Developer Experience
81+
82+
- **VS Code Extension**: `voidflag-vscode`. Utilizing LSP (Language Server Protocol), it provides real-time `.vf` syntax highlighting, JSON schema validation for config files (`voidflag.config.json`), and custom icons.
83+
- **Code Generation**: Prevents typos natively. Instead of guessing a string key, developers get IDE intellisense.
84+
85+
## 8. Key Design Decisions
86+
87+
- **SSE vs Polling (Plan-Based Routing)**: Connection concurrency can be incredibly expensive for backend architectures. By gracefully reverting free-tier users into long-polling architectures, the platform limits expensive active socket limits on the Node.js APIs.
88+
- **djb2 Hashing for Rollouts**: Allows consistent fractional rollouts (e.g., "50% of users"). User X evaluating the flag will always land in the same bucket locally or globally, completely eliminating server-side evaluation calls out to an external system.
89+
- **Schema-First (DSL)**: Hardcoding a schema text file forces a "source of truth". Flags aren't hidden unreachably in a database; they live beside the code.
90+
91+
## 9. Strengths
92+
93+
- **Unmatched Type-Safety**: End-to-end TS types branching straight from a DSL.
94+
- **Pristine Local Development**: The inclusion of an explicit local Dev Server command that mocks the live endpoint eliminates the biggest friction point of feature flags—testing them.
95+
- **Architectural Resilience**: The fallback mechanism smoothly degrades connections from SSE to polling without interrupting the user application.

‎apps/test/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,13 @@
1616
"packageManager": "pnpm@10.28.2",
1717
"dependencies": {
1818
"@types/express": "^5.0.6",
19-
"voidflag-cli": "workspace:*",
20-
"@voidflag/sdk": "workspace:*",
2119
"dotenv": "^17.2.4",
2220
"express": "^5.2.1",
2321
"vitest": "^4.0.18"
2422
},
2523
"devDependencies": {
24+
"voidflag-cli": "workspace:*",
25+
"voidflag": "workspace:*",
2626
"@types/node": "^25.2.3",
2727
"nodemon": "^3.1.14",
2828
"ts-node": "^10.9.2",
Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
// AUTO-GENERATED by VoidFlag
22

3-
import { VoidClient } from '@voidflag/sdk';
3+
import { VoidClient } from 'voidflag';
44
import { schema } from './voidflag.schema.js';
55
console.log('ENV KEY : ', process.env.VF_DEV_KEY);
66
export const vf = new VoidClient({
77
schema,
88
envKey: process.env.VF_DEV_KEY as string,
9+
// dev: true,
910
onConnect: () => console.log('[voidflag] connected'),
1011
onDisconnect: () => console.warn('[voidflag] connection lost'),
1112
});

‎apps/test/src/voidflag/voidflag.schema.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
// This file is auto-generated by VoidFlag. DO NOT EDIT.
33
// ──────────────────────────────────────────────────────────────
44

5-
import type { FlagMap } from '@voidflag/sdk';
5+
import type { FlagMap } from 'voidflag';
66

77
export const schema = {
88
darkMode: { type: 'BOOLEAN', fallback: false },
9-
theme : { type: 'STRING' , fallback: "light" },
10-
fontSize: { type: 'NUMBER' , fallback: 3 },
11-
x : { type: 'BOOLEAN', fallback: false },
9+
theme: { type: 'STRING', fallback: 'light' },
10+
fontSize: { type: 'NUMBER', fallback: 3 },
11+
x: { type: 'BOOLEAN', fallback: false },
1212
} as const satisfies FlagMap;

‎apps/test/src/voidflag/voidflag.state.json‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,13 @@
55
"rollout": 91
66
},
77
"theme": {
8-
"value": "light",
9-
"enabled": false,
8+
"value": "red",
9+
"enabled": true,
1010
"rollout": 62
1111
},
1212
"fontSize": {
1313
"value": 3,
1414
"enabled": false,
1515
"rollout": 100
16-
},
17-
"x": {
18-
"value": false,
19-
"enabled": false,
20-
"rollout": 0
2116
}
2217
}

‎apps/test/voidflag.config.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
"voidflagDir": "src/voidflag",
33
"lang": "ts",
44
"schemaPath": "schema.vf",
5-
"devPort": 4040,
5+
"devPort": 47211,
66
"defaultEnv": "dev",
77
"environments": {
88
"staging": "VF_STAGING_KEY",
99
"dev": "VF_DEV_KEY"
1010
}
11-
}
11+
}

‎packages/CLI/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "voidflag-cli",
3-
"version": "1.0.3",
3+
"version": "1.0.4",
44
"description": "",
55
"main": "dist/index.js",
66
"bin": {

‎packages/CLI/src/codegen/typescript.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ export function generateTypeScript(ast: SchemaAST): string {
7070
'// This file is auto-generated by VoidFlag. DO NOT EDIT.',
7171
'// ──────────────────────────────────────────────────────────────',
7272
'',
73-
"import type { FlagMap } from '@voidflag/sdk';",
73+
"import type { FlagMap } from 'voidflag';",
7474
'',
7575
'export const schema = {',
7676
...flags.map(flagLine),

‎packages/CLI/src/commands/generate.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,16 +84,18 @@ async function generateTs(ast: SchemaAST, outDir: string, cwd: string): Promise<
8484
}
8585

8686
function emitClient(): string {
87-
return `// AUTO-GENERATED by VoidFlag
87+
return `
88+
// AUTO-GENERATED by VoidFlag
8889
89-
import { VoidClient } from '@voidflag/sdk';
90+
import { VoidClient } from 'voidflag';
9091
import { schema } from './voidflag.schema.js';
9192
9293
export const vf = new VoidClient({
9394
schema,
9495
dev: true,
9596
});
9697
98+
9799
`;
98100
}
99101

‎packages/sdk/build.mjs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import { buildSync } from 'esbuild';
2+
3+
buildSync({
4+
entryPoints: ['src/index.ts'],
5+
bundle: true,
6+
platform: 'node',
7+
format: 'esm',
8+
outfile: 'dist/index.js',
9+
external: ['eventsource', 'node:fs', 'node:path'],
10+
});

0 commit comments

Comments
 (0)