@featurevisor/core 2.15.0 → 2.17.0

package/src/generate-code/typescript.ts

@@ -3,12 +3,19 @@ import * as path from "path";
 
 import type {
   Attribute,
+  ParsedFeature,
   Schema,
   VariableSchema,
   VariableSchemaWithInline,
 } from "@featurevisor/types";
 import { Dependencies } from "../dependencies";
 
+export interface TypeScriptGenerationOptions {
+  tag?: string | string[];
+  react?: boolean;
+  individualFeatures?: boolean;
+}
+
 function convertFeaturevisorTypeToTypeScriptType(featurevisorType: string): string {
   switch (featurevisorType) {
     case "boolean":
@@ -32,6 +39,23 @@ function convertFeaturevisorTypeToTypeScriptType(featurevisorType: string): stri
   }
 }
 
+function shouldWrapArrayItemType(typeName: string): boolean {
+  const trimmed = typeName.trim();
+  return trimmed.includes("|") || trimmed.includes("&");
+}
+
+function formatObjectKey(key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}
+
+function formatTypeImport(typeNames: string[], fromPath: string): string {
+  if (typeNames.length === 0) {
+    return "";
+  }
+
+  return `import type {\n${typeNames.map((name) => `  ${name},`).join("\n")}\n} from "${fromPath}";\n\n`;
+}
+
 /**
  * Resolve a schema to its full definition, following schema references (schema: key).
  */
@@ -103,7 +127,8 @@ function schemaToTypeScriptType(
       return literalFromConst ?? unionFromEnum ?? "number";
     case "array":
       if (resolved.items) {
-        return `(${schemaToTypeScriptType(resolved.items, schemasByKey, schemaTypeNames)})[]`;
+        const itemType = schemaToTypeScriptType(resolved.items, schemasByKey, schemaTypeNames);
+        return shouldWrapArrayItemType(itemType) ? `(${itemType})[]` : `${itemType}[]`;
       }
       return "string[]";
     case "object": {
@@ -383,6 +408,63 @@ function getRelativePath(from, to) {
   return relativePath;
 }
 
+function getVariationUnionFromFeature(parsedFeature: ParsedFeature): string | null {
+  if (!parsedFeature.variations || parsedFeature.variations.length === 0) {
+    return null;
+  }
+
+  const values = Array.from(
+    new Set(parsedFeature.variations.map((variation) => JSON.stringify(variation.value))),
+  );
+
+  return values.length > 0 ? values.join(" | ") : null;
+}
+
+function getVariableTypeForFeaturesMap(
+  variableSchema: VariableSchema,
+  schemasByKey: Record<string, Schema>,
+  schemaTypeNames?: Record<string, string>,
+): { typeName: string; schemaTypesUsed: string[] } {
+  const schemaTypesUsed: string[] = [];
+  const addSchemaUsed = (name: string) => {
+    if (name && !schemaTypesUsed.includes(name)) {
+      schemaTypesUsed.push(name);
+    }
+  };
+
+  if (
+    schemaTypeNames &&
+    "schema" in variableSchema &&
+    variableSchema.schema &&
+    schemasByKey[variableSchema.schema]
+  ) {
+    const schemaTypeName = schemaTypeNames[variableSchema.schema];
+    addSchemaUsed(schemaTypeName);
+    return { typeName: schemaTypeName, schemaTypesUsed };
+  }
+
+  const effective = getEffectiveVariableSchema(variableSchema, schemasByKey);
+  if (!effective) {
+    return { typeName: "unknown", schemaTypesUsed };
+  }
+
+  if ("type" in effective && effective.type === "json") {
+    return { typeName: "unknown", schemaTypesUsed };
+  }
+
+  const typeName = schemaToTypeScriptType(effective as Schema, schemasByKey, schemaTypeNames);
+
+  if (schemaTypeNames) {
+    Object.values(schemaTypeNames).forEach((name) => {
+      if (typeName.includes(name)) {
+        addSchemaUsed(name);
+      }
+    });
+  }
+
+  return { typeName, schemaTypesUsed };
+}
+
 /**
  * Generates the content of Schemas.ts: one exported type per schema key, using schema refs between schemas.
  */
@@ -423,8 +505,19 @@ export function getInstance(): FeaturevisorInstance {
 }
 `.trimStart();
 
-export async function generateTypeScriptCodeForProject(deps: Dependencies, outputPath: string) {
+export async function generateTypeScriptCodeForProject(
+  deps: Dependencies,
+  outputPath: string,
+  options: TypeScriptGenerationOptions = {},
+) {
   const { rootDirectoryPath, datasource } = deps;
+  const selectedTags = options.tag
+    ? Array.isArray(options.tag)
+      ? options.tag
+      : [options.tag]
+    : [];
+  const shouldGenerateReact = Boolean(options.react);
+  const shouldGenerateIndividualFeatures = options.individualFeatures !== false;
 
   console.log("\nGenerating TypeScript code...\n");
 
@@ -459,7 +552,7 @@ export async function generateTypeScriptCodeForProject(deps: Dependencies, outpu
     })
     .join("\n");
   const contextContent = `
-import type { AttributeKey, AttributeValue } from "@featurevisor/types";
+import type { AttributeKey, AttributeValue } from "@featurevisor/sdk";
 
 export interface Context {
 ${attributeProperties}
@@ -467,14 +560,13 @@ ${attributeProperties}
 }
 `.trimStart();
 
-  const contextTypeFilePath = path.join(outputPath, "Context.ts");
+  const contextTypeFilePath = path.join(outputPath, "context.ts");
   fs.writeFileSync(contextTypeFilePath, contextContent);
   console.log(
     `Context type file written at: ${getRelativePath(rootDirectoryPath, contextTypeFilePath)}`,
   );
 
   // features
-  const featureNamespaces: string[] = [];
   const featureFiles = await datasource.listFeatures();
 
   // Load schemas for resolving variable schema references
@@ -491,7 +583,7 @@ ${attributeProperties}
   const hasSchemasFile = schemaKeys.length > 0;
   if (hasSchemasFile) {
     const schemasContent = generateSchemasFileContent(schemaKeys, schemasByKey);
-    const schemasFilePath = path.join(outputPath, "Schemas.ts");
+    const schemasFilePath = path.join(outputPath, "schemas.ts");
     fs.writeFileSync(schemasFilePath, schemasContent);
     console.log(
       `Schemas type file written at: ${getRelativePath(rootDirectoryPath, schemasFilePath)}`,
@@ -503,90 +595,107 @@ ${attributeProperties}
     schemaTypeNames[k] = getPascalCase(k) + "Schema";
   }
 
+  const parsedFeatures: {
+    featureKey: string;
+    parsedFeature: ParsedFeature;
+    namespaceValue: string;
+  }[] = [];
+
   for (const featureKey of featureFiles) {
-    const parsedFeature = await datasource.readFeature(featureKey);
+    const parsedFeature = (await datasource.readFeature(featureKey)) as ParsedFeature;
 
     if (typeof parsedFeature.archived !== "undefined" && parsedFeature.archived) {
       continue;
     }
 
-    const namespaceValue = getPascalCase(featureKey) + "Feature";
-    featureNamespaces.push(namespaceValue);
-
-    let variableTypeDeclarations = "";
-    let variableMethods = "";
-    const featureSchemaTypesUsed = new Set<string>();
-
-    if (parsedFeature.variablesSchema) {
-      const variableKeys = Object.keys(parsedFeature.variablesSchema);
-      const allDeclarations: string[] = [];
-
-      for (const variableKey of variableKeys) {
-        const variableSchema = parsedFeature.variablesSchema[variableKey];
-        const effective = getEffectiveVariableSchema(variableSchema, schemasByKey);
-        const variableType = effective?.type;
-        const {
-          declarations,
-          returnTypeName,
-          genericArg,
-          isLiteralType,
-          useGetVariable,
-          schemaTypesUsed,
-        } = generateVariableTypeDeclarations(
-          variableKey,
-          variableSchema,
-          schemasByKey,
-          hasSchemasFile ? schemaTypeNames : undefined,
-        );
-        schemaTypesUsed.forEach((t) => featureSchemaTypesUsed.add(t));
-        allDeclarations.push(...declarations);
+    if (selectedTags.length > 0) {
+      const featureTags = Array.isArray(parsedFeature.tags) ? parsedFeature.tags : [];
+      const hasTags = selectedTags.every((tag) => featureTags.includes(tag));
+      if (!hasTags) {
+        continue;
+      }
+    }
 
-        const internalMethodName = `getVariable${
-          variableType === "json" ? "JSON" : getPascalCase(variableType ?? "string")
-        }`;
+    const namespaceValue = getPascalCase(featureKey) + "Feature";
+    parsedFeatures.push({ featureKey, parsedFeature, namespaceValue });
+  }
 
-        const hasGeneric =
-          variableType === "json" || variableType === "array" || variableType === "object";
-        const literalAssertion = isLiteralType ? ` as ${returnTypeName} | null` : "";
-        if (useGetVariable) {
-          variableMethods += `
+  const featureNamespaces: string[] = [];
+  if (shouldGenerateIndividualFeatures) {
+    for (const { featureKey, parsedFeature, namespaceValue } of parsedFeatures) {
+      featureNamespaces.push(namespaceValue);
+
+      let variableTypeDeclarations = "";
+      let variableMethods = "";
+      const featureSchemaTypesUsed = new Set<string>();
+
+      if (parsedFeature.variablesSchema) {
+        const variableKeys = Object.keys(parsedFeature.variablesSchema);
+        const allDeclarations: string[] = [];
+
+        for (const variableKey of variableKeys) {
+          const variableSchema = parsedFeature.variablesSchema[variableKey];
+          const effective = getEffectiveVariableSchema(variableSchema, schemasByKey);
+          const variableType = effective?.type;
+          const {
+            declarations,
+            returnTypeName,
+            genericArg,
+            isLiteralType,
+            useGetVariable,
+            schemaTypesUsed,
+          } = generateVariableTypeDeclarations(
+            variableKey,
+            variableSchema,
+            schemasByKey,
+            hasSchemasFile ? schemaTypeNames : undefined,
+          );
+          schemaTypesUsed.forEach((t) => featureSchemaTypesUsed.add(t));
+          allDeclarations.push(...declarations);
+
+          const internalMethodName = `getVariable${
+            variableType === "json" ? "JSON" : getPascalCase(variableType ?? "string")
+          }`;
+
+          const hasGeneric =
+            variableType === "json" || variableType === "array" || variableType === "object";
+          const literalAssertion = isLiteralType ? ` as ${returnTypeName} | null` : "";
+          if (useGetVariable) {
+            variableMethods += `
 
 ${INDENT_NS}export function get${getPascalCase(variableKey)}(context: Context = {}): ${returnTypeName} | null {
 ${INDENT_NS_BODY}return getInstance().getVariable(key, "${variableKey}", context)${literalAssertion};
 ${INDENT_NS}}`;
-        } else if (variableType === "json") {
-          variableMethods += `
+          } else if (variableType === "json") {
+            variableMethods += `
 
 ${INDENT_NS}export function get${getPascalCase(variableKey)}<T = unknown>(context: Context = {}): T | null {
 ${INDENT_NS_BODY}return getInstance().${internalMethodName}<T>(key, "${variableKey}", context);
 ${INDENT_NS}}`;
-        } else if (hasGeneric) {
-          variableMethods += `
+          } else if (hasGeneric) {
+            variableMethods += `
 
 ${INDENT_NS}export function get${getPascalCase(variableKey)}(context: Context = {}): ${returnTypeName} | null {
 ${INDENT_NS_BODY}return getInstance().${internalMethodName}<${genericArg}>(key, "${variableKey}", context);
 ${INDENT_NS}}`;
-        } else {
-          variableMethods += `
+          } else {
+            variableMethods += `
 
 ${INDENT_NS}export function get${getPascalCase(variableKey)}(context: Context = {}): ${returnTypeName} | null {
 ${INDENT_NS_BODY}return getInstance().${internalMethodName}(key, "${variableKey}", context)${literalAssertion};
 ${INDENT_NS}}`;
+          }
         }
-      }
 
-      if (allDeclarations.length > 0) {
-        variableTypeDeclarations = "\n\n" + allDeclarations.join("\n\n");
+        if (allDeclarations.length > 0) {
+          variableTypeDeclarations = "\n\n" + allDeclarations.join("\n\n");
+        }
       }
-    }
 
-    const schemasImportLine =
-      featureSchemaTypesUsed.size > 0
-        ? `import type { ${[...featureSchemaTypesUsed].sort().join(", ")} } from "./Schemas";\n\n`
-        : "";
+      const schemasImportLine = formatTypeImport([...featureSchemaTypesUsed].sort(), "./schemas");
 
-    const featureContent = `
-import { Context } from "./Context";
+      const featureContent = `
+import { Context } from "./context";
 import { getInstance } from "./instance";
 ${schemasImportLine}export namespace ${namespaceValue} {
 ${INDENT_NS}export const key = "${featureKey}";${variableTypeDeclarations}
@@ -601,22 +710,146 @@ ${INDENT_NS}}${variableMethods}
 }
 `.trimStart();
 
-    const featureNamespaceFilePath = path.join(outputPath, `${namespaceValue}.ts`);
-    fs.writeFileSync(featureNamespaceFilePath, featureContent);
-    console.log(
-      `Feature ${featureKey} file written at: ${getRelativePath(
-        rootDirectoryPath,
-        featureNamespaceFilePath,
-      )}`,
-    );
+      const featureNamespaceFilePath = path.join(outputPath, `${namespaceValue}.ts`);
+      fs.writeFileSync(featureNamespaceFilePath, featureContent);
+      console.log(
+        `Feature ${featureKey} file written at: ${getRelativePath(
+          rootDirectoryPath,
+          featureNamespaceFilePath,
+        )}`,
+      );
+    }
+  }
+
+  const featuresTypeSchemasUsed = new Set<string>();
+  const featureTypeEntries = parsedFeatures
+    .map(({ featureKey, parsedFeature }) => {
+      const featureLines: string[] = [];
+      const variationUnion = getVariationUnionFromFeature(parsedFeature);
+
+      if (variationUnion) {
+        featureLines.push(`${INDENT_NS_BODY}variation: ${variationUnion};`);
+      }
+
+      if (parsedFeature.variablesSchema) {
+        for (const [variableKey, variableSchema] of Object.entries(parsedFeature.variablesSchema)) {
+          const { typeName, schemaTypesUsed } = getVariableTypeForFeaturesMap(
+            variableSchema,
+            schemasByKey,
+            hasSchemasFile ? schemaTypeNames : undefined,
+          );
+          schemaTypesUsed.forEach((name) => featuresTypeSchemasUsed.add(name));
+          featureLines.push(`${INDENT_NS_BODY}${formatObjectKey(variableKey)}: ${typeName};`);
+        }
+      }
+
+      if (featureLines.length === 0) {
+        return `${INDENT_NS}${formatObjectKey(featureKey)}: null;`;
+      }
+
+      return `${INDENT_NS}${formatObjectKey(featureKey)}: {\n${featureLines.join("\n")}\n${INDENT_NS}};`;
+    })
+    .join("\n");
+
+  const featuresSchemasImportLine = formatTypeImport(
+    [...featuresTypeSchemasUsed].sort(),
+    "./schemas",
+  );
+
+  const featuresFileContent = `
+${featuresSchemasImportLine}export type Features = {
+${featureTypeEntries}
+};
+
+export type FeatureKey = keyof Features;
+export type VariableKey<F extends FeatureKey> = Features[F] extends Record<string, unknown>
+  ? Extract<Exclude<keyof Features[F], "variation">, string>
+  : never;
+export type VariableType<F extends FeatureKey, V extends VariableKey<F>> = Features[F] extends Record<string, unknown>
+  ? Features[F][V]
+  : never;
+export type Variation<F extends FeatureKey> = Features[F] extends { variation: infer V }
+  ? V
+  : never;
+`.trimStart();
+  const featuresFilePath = path.join(outputPath, "features.ts");
+  fs.writeFileSync(featuresFilePath, featuresFileContent);
+  console.log(`Features file written at: ${getRelativePath(rootDirectoryPath, featuresFilePath)}`);
+
+  const functionsFileContent = `
+import { FeatureKey, Variation, VariableKey, VariableType } from "./features";
+import { Context } from "./context";
+import { getInstance } from "./instance";
+
+export function isEnabled(featureKey: FeatureKey, context: Context = {}): boolean {
+  return getInstance().isEnabled(featureKey, context);
+}
+
+export function getVariation<F extends FeatureKey>(
+  featureKey: F,
+  context: Context = {},
+): Variation<F> | null {
+  return getInstance().getVariation(featureKey, context) as Variation<F> | null;
+}
+
+export function getVariable<F extends FeatureKey, V extends VariableKey<F>>(
+  featureKey: F,
+  variableKey: V,
+  context: Context = {},
+): VariableType<F, V> | null {
+  return getInstance().getVariable(featureKey, variableKey, context) as VariableType<F, V> | null;
+}
+`.trimStart();
+  const functionsFilePath = path.join(outputPath, "functions.ts");
+  fs.writeFileSync(functionsFilePath, functionsFileContent);
+  console.log(
+    `Functions file written at: ${getRelativePath(rootDirectoryPath, functionsFilePath)}`,
+  );
+
+  if (shouldGenerateReact) {
+    const reactFileContent = `
+import {
+  useFlag as useFlagOriginal,
+  useVariation as useVariationOriginal,
+  useVariable as useVariableOriginal,
+} from "@featurevisor/react";
+
+import { FeatureKey, Variation, VariableKey, VariableType } from "./features";
+import { Context } from "./context";
+
+export function useFlag(featureKey: FeatureKey, context: Context = {}): boolean {
+  return useFlagOriginal(featureKey, context);
+}
+
+export function useVariation<F extends FeatureKey>(
+  featureKey: F,
+  context: Context = {},
+): Variation<F> | null {
+  return useVariationOriginal(featureKey, context) as Variation<F> | null;
+}
+
+export function useVariable<F extends FeatureKey, V extends VariableKey<F>>(
+  featureKey: F,
+  variableKey: V,
+  context: Context = {},
+): VariableType<F, V> | null {
+  return useVariableOriginal(featureKey, variableKey, context) as VariableType<F, V> | null;
+}
+`.trimStart();
+    const reactFilePath = path.join(outputPath, "react.ts");
+    fs.writeFileSync(reactFilePath, reactFileContent);
+    console.log(`React file written at: ${getRelativePath(rootDirectoryPath, reactFilePath)}`);
   }
 
   // index
   const indexContent =
     [
-      `export * from "./Context";`,
+      `export * from "./context";`,
       `export * from "./instance";`,
-      ...(hasSchemasFile ? [`export * from "./Schemas";`] : []),
+      ...(hasSchemasFile ? [`export * from "./schemas";`] : []),
+      `export * from "./features";`,
+      `export * from "./functions";`,
+      ...(shouldGenerateReact ? [`export * from "./react";`] : []),
       ...featureNamespaces.map((featureNamespace) => {
         return `export * from "./${featureNamespace}";`;
       }),