feat: typed feature flags (#76

Feature flags are now typed, this has two benefits:

- Easier for users to enable flags, as they'll see features in
intellisense,
- Users are reminded to remove flags that have been removed from the
sdk,

Author: smeijer

.changeset/few-dolphins-fry.md

@@ -0,0 +1,5 @@
+---
+'magicbell': patch
+---
+
+Feature flags are now typed, making it easier to enable beta features, and harder to forget removing flags when beta features turned stable.

packages/magicbell/README.md

@@ -316,10 +316,10 @@ Below is a list of features that are currently behind feature flags.
 
 | Feature Flag                      | Description                                                                |
 | --------------------------------- | -------------------------------------------------------------------------- |
-| `users-push-subscriptions-list`   | Fetch user's push subscriptions ([docs](#users-push-subscriptions-list))   |
-| `users-push-subscriptions-delete` | Delete user's push subscription ([docs](#users-push-subscriptions-delete)) |
 | `imports-create`                  | Create a import ([docs](#imports-create))                                  |
 | `imports-get`                     | Get the status of an import ([docs](#imports-get))                         |
+| `users-push-subscriptions-delete` | Delete user's push subscription ([docs](#users-push-subscriptions-delete)) |
+| `users-push-subscriptions-list`   | Fetch user's push subscriptions ([docs](#users-push-subscriptions-list))   |
 
 <!-- AUTO-GENERATED-CONTENT:END (FEATURE_FLAGS) -->
 

packages/magicbell/scripts/generate-resources.ts

@@ -306,6 +306,37 @@ function createFeatureFlagTable(methods: Method[]) {
   return lines.join('\n');
 }
 
+async function updateTypes(filePath: string, betaMethods: Method[]) {
+  const source = await fs.readFile(filePath, 'utf-8');
+  const ast = recast.parse(source);
+  const program = ast.program;
+
+  const clientOptions = program.body.find(
+    (x) => x.type === 'ExportNamedDeclaration' && x.declaration.id.name === 'ClientOptions',
+  );
+
+  const features = clientOptions.declaration.typeAnnotation.members.find((x) => x.key.name === 'features');
+
+  features.typeAnnotation = builders.tsTypeAnnotation.from({
+    typeAnnotation: builders.tsTypeLiteral.from({
+      members: betaMethods.map((method) =>
+        builders.tsPropertySignature.from({
+          optional: true,
+          key: builders.stringLiteral(method.operationId),
+          typeAnnotation: builders.tsTypeAnnotation.from({
+            typeAnnotation: builders.tsLiteralType.from({
+              literal: builders.booleanLiteral(true),
+            }),
+          }),
+        }),
+      ),
+    }),
+  });
+
+  const output = await recast.print(ast, false);
+  if (!output) return;
+  await fs.writeFile(filePath, output, 'utf-8');
+}
 async function updateClient(filePath: string, files: File[]) {
   const resources = files
     .filter((x) => x.type === 'resources' && x.name.endsWith('.ts'))
@@ -366,7 +397,10 @@ async function main() {
   const resources = await getResources(argv.spec || SPEC_URL);
 
   const files: Array<File> = [];
-  const betaMethods = resources.flatMap((x) => x.methods).filter((x) => x.beta);
+  const betaMethods = resources
+    .flatMap((x) => x.methods)
+    .filter((x) => x.beta)
+    .sort((a, b) => a.operationId.localeCompare(b.operationId));
 
   // generate ast for new resource files
   for (const rootResource of resources) {
@@ -430,6 +464,7 @@ async function main() {
   await updateReadme(README_MD, 'FEATURE_FLAGS', createFeatureFlagTable(betaMethods));
   console.log(`updated README.md`);
 
+  await updateTypes(path.join(process.cwd(), 'src', 'types.ts'), betaMethods);
   await updateClient(path.join(process.cwd(), 'src', 'client.ts'), files);
   console.log(`updated ${path.relative(process.cwd(), path.join('src', 'client.ts'))}`);
 }

packages/magicbell/src/client.ts

@@ -14,7 +14,7 @@ import { Notifications } from './resources/notifications';
 import { PushSubscriptions } from './resources/push-subscriptions';
 import { Subscriptions } from './resources/subscriptions';
 import { Users } from './resources/users';
-import { ClientOptions, RequestArgs, RequestMethod, RequestOptions } from './types';
+import { ClientOptions, FeatureFlag, RequestArgs, RequestMethod, RequestOptions } from './types';
 
 // some environments, like vscode extensions, don't have the XMLHttpRequest object defined.
 if (typeof XMLHttpRequest !== 'function') {
@@ -36,7 +36,7 @@ export class Client {
   #clientUserAgent: string;
   #options: ClientOptions;
   #logger = new Logger();
-  #features: Record<string, boolean> = {};
+  #features: ClientOptions['features'] = {};
   #lastRequest: Telemetry[] = [];
   listen = createListener(this);
 
@@ -66,7 +66,7 @@ export class Client {
     this.#features = options.features || {};
   }
 
-  hasFlag(flag: string) {
+  hasFlag(flag: FeatureFlag) {
     return this.#features[flag] || false;
   }
 

packages/magicbell/src/resource.ts

@@ -2,6 +2,7 @@ import { Client } from './client';
 import { joinUrlSegments } from './lib/utils';
 import { IterablePromise, normalizeArgs } from './method';
 import { autoPaginate } from './paginate';
+import { FeatureFlag } from './types';
 
 type ResourceRequestOptions = {
   method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'PATCH';
@@ -66,7 +67,7 @@ export class Resource {
     return makeRequest({ data, params });
   }
 
-  protected assertFeatureFlag(flag: string) {
+  protected assertFeatureFlag(flag: FeatureFlag) {
     if (!this.client.hasFlag(flag)) {
       throw new Error(`This is a beta feature, please enable it by providing the "${flag}" feature flag.`);
     }

packages/magicbell/src/types.ts

@@ -16,10 +16,17 @@ export type ClientOptions = {
   idempotencyKey?: string;
   telemetry?: boolean;
   debug?: boolean;
-  features?: Record<string, boolean>;
+  features?: {
+    'imports-create'?: true;
+    'imports-get'?: true;
+    'users-push-subscriptions-delete'?: true;
+    'users-push-subscriptions-list'?: true;
+  };
   headers?: Record<string, string>;
 };
 
+export type FeatureFlag = keyof ClientOptions['features'];
+
 export type RequestOptions = {
   userEmail?: string;
   userExternalId?: string;