algolia-codegen 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 nightlightmare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,12 +1,20 @@
 # Algolia Type Generator
 
+[![npm version](https://img.shields.io/npm/v/algolia-codegen.svg?style=flat-square)](https://www.npmjs.com/package/algolia-codegen)
+[![npm downloads](https://img.shields.io/npm/dm/algolia-codegen.svg?style=flat-square)](https://www.npmjs.com/package/algolia-codegen)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/algolia-codegen?style=flat-square)](https://bundlephobia.com/package/algolia-codegen)
+[![GitHub stars](https://img.shields.io/github/stars/nightlightmare/algolia-codegen.svg?style=flat-square&logo=github)](https://github.com/nightlightmare/algolia-codegen)
+[![GitHub issues](https://img.shields.io/github/issues/nightlightmare/algolia-codegen.svg?style=flat-square&logo=github)](https://github.com/nightlightmare/algolia-codegen/issues)
+[![GitHub license](https://img.shields.io/github/license/nightlightmare/algolia-codegen.svg?style=flat-square)](https://github.com/nightlightmare/algolia-codegen/blob/main/LICENSE)
+[![Node.js version](https://img.shields.io/node/v/algolia-codegen.svg?style=flat-square)](https://nodejs.org/)
+
 This script automatically generates TypeScript types from your Algolia indices by fetching sample records and analyzing their structure. It supports multiple indices and flexible configuration through a config file.
 
 **Repository**: [https://github.com/nightlightmare/algolia-codegen](https://github.com/nightlightmare/algolia-codegen)
 
 ## Prerequisites
 
-- Node.js >= 18
+- Node.js >= 20
 - Algolia account with at least one index
 
 ## Installation
@@ -30,17 +38,17 @@ yarn add algolia-codegen
 1. Create a configuration file named `algolia-codegen.ts` (or `.js`) in your project root:
 
 ```typescript
-import type { AlgoliaCodegenConfig } from "algolia-codegen";
+import type { AlgoliaCodegenConfig } from 'algolia-codegen';
 
 const config: AlgoliaCodegenConfig = {
   overwrite: true,
   generates: {
-    "src/algolia/types.ts": {
-      appId: "YOUR_APP_ID",
-      searchKey: "YOUR_SEARCH_API_KEY",
-      indexName: "products",
-      prefix: "Algolia", // Optional
-      postfix: "Type", // Optional
+    'src/algolia/types.ts': {
+      appId: 'YOUR_APP_ID',
+      searchKey: 'YOUR_SEARCH_API_KEY',
+      indexName: 'products',
+      prefix: 'Algolia', // Optional
+      postfix: 'Type', // Optional
     },
   },
 };
@@ -65,17 +73,17 @@ npx algolia-codegen
 Create a configuration file named `algolia-codegen.ts` (or `.js`) in your project root. The config file should export a default object with the following structure:
 
 ```typescript
-import type { AlgoliaCodegenConfig } from "algolia-codegen";
+import type { AlgoliaCodegenConfig } from 'algolia-codegen';
 
 const config: AlgoliaCodegenConfig = {
   overwrite: true,
   generates: {
-    "src/algolia/types.ts": {
-      appId: "YOUR_APP_ID",
-      searchKey: "YOUR_SEARCH_API_KEY",
-      indexName: "products",
-      prefix: "Algolia", // Optional
-      postfix: "Type", // Optional
+    'src/algolia/types.ts': {
+      appId: 'YOUR_APP_ID',
+      searchKey: 'YOUR_SEARCH_API_KEY',
+      indexName: 'products',
+      prefix: 'Algolia', // Optional
+      postfix: 'Type', // Optional
     },
   },
 };
@@ -91,15 +99,15 @@ You can generate types for multiple indices:
 const config: AlgoliaCodegenConfig = {
   overwrite: true,
   generates: {
-    "src/algolia/products.ts": {
-      appId: "YOUR_APP_ID",
-      searchKey: "YOUR_SEARCH_API_KEY",
-      indexName: "products",
+    'src/algolia/products.ts': {
+      appId: 'YOUR_APP_ID',
+      searchKey: 'YOUR_SEARCH_API_KEY',
+      indexName: 'products',
     },
-    "src/algolia/users.ts": {
-      appId: "YOUR_APP_ID",
-      searchKey: "YOUR_SEARCH_API_KEY",
-      indexName: "users",
+    'src/algolia/users.ts': {
+      appId: 'YOUR_APP_ID',
+      searchKey: 'YOUR_SEARCH_API_KEY',
+      indexName: 'users',
     },
   },
 };
@@ -114,17 +122,17 @@ const config: AlgoliaCodegenConfig = {
   overwrite: true,
   generates: [
     {
-      "src/algolia/products.ts": {
-        appId: "YOUR_APP_ID",
-        searchKey: "YOUR_SEARCH_API_KEY",
-        indexName: "products",
+      'src/algolia/products.ts': {
+        appId: 'YOUR_APP_ID',
+        searchKey: 'YOUR_SEARCH_API_KEY',
+        indexName: 'products',
       },
     },
     {
-      "src/algolia/users.ts": {
-        appId: "YOUR_APP_ID",
-        searchKey: "YOUR_SEARCH_API_KEY",
-        indexName: "users",
+      'src/algolia/users.ts': {
+        appId: 'YOUR_APP_ID',
+        searchKey: 'YOUR_SEARCH_API_KEY',
+        indexName: 'users',
       },
     },
   ],
@@ -141,7 +149,15 @@ After installation, you can use the CLI command:
 algolia-codegen
 ```
 
-Or specify a custom config file:
+#### Options
+
+- `-c, --config <path>` - Specify a custom config file path
+- `-v, --verbose` - Enable verbose output (shows detailed logging)
+- `--dry-run` - Simulate execution without writing files (useful for testing)
+
+#### Examples
+
+Specify a custom config file:
 
 ```bash
 algolia-codegen --config path/to/config.ts
@@ -149,6 +165,26 @@ algolia-codegen --config path/to/config.ts
 algolia-codegen -c path/to/config.ts
 ```
 
+Enable verbose output:
+
+```bash
+algolia-codegen --verbose
+# or
+algolia-codegen -v
+```
+
+Run in dry-run mode (no files will be written):
+
+```bash
+algolia-codegen --dry-run
+```
+
+Combine options:
+
+```bash
+algolia-codegen --config custom-config.ts --verbose --dry-run
+```
+
 Or if installed locally:
 
 ```bash
@@ -187,13 +223,13 @@ type AlgoliaCodegenGeneratorConfig = {
    - Fetches a sample record from the specified index
    - Analyzes the record structure and generates TypeScript types
    - Creates a single TypeScript file containing all types found in the index
-3. **Type Generation**: The generator automatically:
+4. **Type Generation**: The generator automatically:
    - Infers types from the sample record structure
    - Handles nested objects, arrays, and complex types
    - Detects and generates generic `IdValue<T>` types for Algolia's id-value pattern arrays
    - Generates proper TypeScript interfaces with JSDoc comments
    - Sorts types by dependencies for correct ordering
-4. **Error Handling**: Continues processing other files even if one fails, with detailed error messages
+5. **Error Handling**: Continues processing other files even if one fails, with detailed error messages
 
 Each generated file contains all types found in the index, including nested types, properly organized and sorted by dependencies.
 
@@ -213,44 +249,12 @@ Each generated file contains all types found in the index, including nested type
 
 ## Examples
 
-### Generated Type Example
-
-Given an Algolia record like:
-
-```json
-{
-  "objectID": "123",
-  "name": "Product Name",
-  "price": 99.99,
-  "tags": ["tag1", "tag2"],
-  "metadata": {
-    "category": "electronics",
-    "rating": 4.5
-  }
-}
-```
-
-The generator will create TypeScript types:
+See the [examples directory](./examples/) for comprehensive examples including:
 
-```typescript
-/**
- * Generated TypeScript types for Algolia index: products
- * This file is auto-generated. Do not edit manually.
- */
-
-export interface AlgoliaHitType {
-  metadata: AlgoliaMetadataType;
-  name: string;
-  objectID: string;
-  price: number;
-  tags: string[];
-}
-
-export interface AlgoliaMetadataType {
-  category: string;
-  rating: number;
-}
-```
+- Framework integrations (Next.js, React, Vue)
+- CI/CD integration (GitHub Actions)
+- Custom prefixes/postfixes
+- Multiple indices configuration
 
 ## Repository
 

package/dist/{chunk-R66ECGLW.js → chunk-USMYY2DN.js}

@@ -11,7 +11,7 @@ async function loadTypeScriptConfig(resolvedPath) {
   const result = esbuild.transformSync(source, {
     loader: "ts",
     format: "esm",
-    target: "node18",
+    target: "node20",
     sourcefile: resolvedPath
   });
   if (!result.code) {
@@ -25,10 +25,8 @@ async function loadTypeScriptConfig(resolvedPath) {
 // src/utils/validations/generator-config.ts
 function validateGeneratorConfig(config, path) {
   if (typeof config !== "object" || config === null || Array.isArray(config)) {
-    throw new Error(
-      `Invalid generator config: must be an object
-Path: ${path}`
-    );
+    throw new Error(`Invalid generator config: must be an object
+Path: ${path}`);
   }
   const cfg = config;
   const requiredFields = [
@@ -70,10 +68,8 @@ Received: ${typeof cfg.postfix}`
 // src/utils/validations/url-schema.ts
 function validateUrlSchema(urlSchema, path) {
   if (typeof urlSchema !== "object" || urlSchema === null || Array.isArray(urlSchema)) {
-    throw new Error(
-      `Invalid generates entry: must be an object
-Path: ${path}`
-    );
+    throw new Error(`Invalid generates entry: must be an object
+Path: ${path}`);
   }
   const schema = urlSchema;
   for (const [filePath, generatorConfig] of Object.entries(schema)) {
@@ -90,10 +86,8 @@ Path: ${path}[${filePath}]`
 // src/utils/validations/config.ts
 function validateConfig(config, configPath) {
   if (typeof config !== "object" || config === null || Array.isArray(config)) {
-    throw new Error(
-      `Invalid config: must be an object
-Config file: ${configPath}`
-    );
+    throw new Error(`Invalid config: must be an object
+Config file: ${configPath}`);
   }
   const cfg = config;
   if (!("overwrite" in cfg)) {
@@ -174,10 +168,8 @@ Make sure esbuild is installed as a dependency.`
       configModule = await import(configUrl);
     } catch (importError) {
       const errorMessage = importError instanceof Error ? importError.message : String(importError);
-      throw new Error(
-        `Failed to import config file: ${resolvedPath}
-Error: ${errorMessage}`
-      );
+      throw new Error(`Failed to import config file: ${resolvedPath}
+Error: ${errorMessage}`);
     }
   }
   if (!configModule.default) {
@@ -306,7 +298,7 @@ var TypeGenerator = class {
       return `${this.prefix}Hit${this.postfix}`;
     }
     const lastPart = path[path.length - 1];
-    const parts = lastPart.replace(/[\[\]]/g, "").split(/[-_\s]+/).filter(Boolean);
+    const parts = lastPart.replace(/[[\]]/g, "").split(/[-_\s]+/).filter(Boolean);
     const pascalCase = parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join("");
     if (path.length > 1) {
       const parent = path[path.length - 2];
@@ -458,30 +450,34 @@ function generateTypeScriptTypes(sampleHit, config) {
 }
 
 // src/utils/fetch-algolia-data.ts
-async function fetchAlgoliaData(filePath, generatorConfig, overwrite) {
-  console.log(`
-Processing file: ${filePath}`);
+async function fetchAlgoliaData(filePath, generatorConfig, overwrite, logger) {
+  logger.info(`Processing file: ${filePath}`);
   const resolvedPath = resolve2(process.cwd(), filePath);
+  logger.verbose(`Resolved path: ${resolvedPath}`);
   if (existsSync2(resolvedPath) && !overwrite) {
     throw new Error(
       `File already exists: ${resolvedPath}
 Set overwrite: true in config to allow overwriting existing files.`
     );
   }
-  console.log(`Connecting to Algolia...`);
-  console.log(`App ID: ${generatorConfig.appId}`);
+  const connectSpinner = logger.spinner("Connecting to Algolia...");
+  connectSpinner.start();
   let client;
   try {
-    client = algoliasearch(
-      generatorConfig.appId,
-      generatorConfig.searchKey
-    );
+    logger.verbose(`App ID: ${generatorConfig.appId}`);
+    logger.verbose(`Index: ${generatorConfig.indexName}`);
+    client = algoliasearch(generatorConfig.appId, generatorConfig.searchKey);
+    connectSpinner.succeed("Connected to Algolia");
   } catch (error) {
+    connectSpinner.fail("Failed to connect to Algolia");
     throw new Error(
       `Failed to initialize Algolia client: ${error instanceof Error ? error.message : String(error)}`
     );
   }
-  console.log(`Fetching sample record from index: ${generatorConfig.indexName}`);
+  const fetchSpinner = logger.spinner(
+    `Fetching sample record from index: ${generatorConfig.indexName}`
+  );
+  fetchSpinner.start();
   let results;
   try {
     results = await client.search([
@@ -493,7 +489,9 @@ Set overwrite: true in config to allow overwriting existing files.`
         }
       }
     ]);
+    fetchSpinner.succeed("Sample record fetched successfully");
   } catch (error) {
+    fetchSpinner.fail("Failed to fetch data from Algolia");
     let errorMessage;
     if (error instanceof Error) {
       errorMessage = error.message;
@@ -525,52 +523,183 @@ Set overwrite: true in config to allow overwriting existing files.`
     throw new Error(`No hits found in Algolia index: ${generatorConfig.indexName}`);
   }
   const sampleHit = result.hits[0];
-  console.log("Sample record fetched successfully");
-  console.log(`ObjectID: ${sampleHit.objectID || "N/A"}`);
+  logger.verbose(`ObjectID: ${sampleHit.objectID || "N/A"}`);
+  const generateSpinner = logger.spinner("Generating TypeScript types...");
+  generateSpinner.start();
   const fileContent = generateTypeScriptTypes(sampleHit, generatorConfig);
+  generateSpinner.succeed("TypeScript types generated");
   const dir = dirname(resolvedPath);
   if (!existsSync2(dir)) {
-    mkdirSync(dir, { recursive: true });
+    if (!logger.isDryRun) {
+      mkdirSync(dir, { recursive: true });
+      logger.verbose(`Created directory: ${dir}`);
+    } else {
+      logger.dryRun(`Would create directory: ${dir}`);
+    }
+  }
+  if (logger.isDryRun) {
+    logger.dryRun(`Would write file: ${filePath}`);
+    logger.verbose(`File content length: ${fileContent.length} characters`);
+  } else {
+    writeFileSync(resolvedPath, fileContent, "utf-8");
+    logger.success(`Generated file: ${filePath}`);
   }
-  writeFileSync(resolvedPath, fileContent, "utf-8");
-  console.log(`Generated file: ${filePath}`);
 }
 
+// src/utils/logger.ts
+import chalk from "chalk";
+import ora from "ora";
+var Logger = class {
+  _verbose;
+  _dryRun;
+  constructor(options = {}) {
+    this._verbose = options.verbose ?? false;
+    this._dryRun = options.dryRun ?? false;
+  }
+  /**
+   * Check if verbose mode is enabled
+   */
+  get isVerbose() {
+    return this._verbose;
+  }
+  /**
+   * Check if dry-run mode is enabled
+   */
+  get isDryRun() {
+    return this._dryRun;
+  }
+  /**
+   * Log info message (always shown)
+   */
+  info(message) {
+    console.log(chalk.blue("\u2139"), message);
+  }
+  /**
+   * Log success message (always shown)
+   */
+  success(message) {
+    console.log(chalk.green("\u2713"), message);
+  }
+  /**
+   * Log warning message (always shown)
+   */
+  warn(message) {
+    console.log(chalk.yellow("\u26A0"), message);
+  }
+  /**
+   * Log error message (always shown)
+   */
+  error(message) {
+    console.error(chalk.red("\u2717"), message);
+  }
+  /**
+   * Log verbose message (only shown in verbose mode)
+   */
+  verbose(message) {
+    if (this._verbose) {
+      console.log(chalk.gray("\u2192"), message);
+    }
+  }
+  /**
+   * Log dry-run message (only shown in dry-run mode)
+   */
+  dryRun(message) {
+    if (this._dryRun) {
+      console.log(chalk.cyan("[DRY-RUN]"), message);
+    }
+  }
+  /**
+   * Create a spinner for long-running operations
+   */
+  spinner(text) {
+    return ora({
+      text,
+      color: "cyan",
+      spinner: "dots"
+    });
+  }
+  /**
+   * Log file operation (respects dry-run)
+   */
+  fileOperation(action, filePath) {
+    if (this._dryRun) {
+      this.dryRun(`Would ${action}: ${chalk.underline(filePath)}`);
+    } else {
+      this.verbose(`${action}: ${filePath}`);
+    }
+  }
+  /**
+   * Format error with context
+   */
+  formatError(error, context) {
+    let errorMessage = "";
+    if (error instanceof Error) {
+      errorMessage = error.message;
+      if (this._verbose && error.stack) {
+        errorMessage += `
+${chalk.gray(error.stack)}`;
+      }
+    } else if (error && typeof error === "object") {
+      const errorObj = error;
+      if (errorObj.message) {
+        errorMessage = String(errorObj.message);
+      } else if (errorObj.status) {
+        errorMessage = `HTTP ${errorObj.status}: ${errorObj.statusText || "Unknown error"}`;
+      } else {
+        try {
+          errorMessage = JSON.stringify(error, null, 2);
+        } catch {
+          errorMessage = String(error);
+        }
+      }
+    } else {
+      errorMessage = String(error);
+    }
+    if (context) {
+      return `${chalk.red(context)}
+${errorMessage}`;
+    }
+    return errorMessage;
+  }
+};
+var logger_default = Logger;
+
 // src/index.ts
-var main = async (configPath) => {
+var main = async (options) => {
+  const opts = typeof options === "string" ? { configPath: options } : options ?? {};
+  const logger = new logger_default({
+    verbose: opts.verbose ?? false,
+    dryRun: opts.dryRun ?? false
+  });
   try {
-    const config = await loadConfig(configPath);
-    console.log("Config loaded successfully");
+    const configSpinner = logger.spinner("Loading configuration...");
+    configSpinner.start();
+    const config = await loadConfig(opts.configPath);
+    configSpinner.succeed("Configuration loaded successfully");
+    logger.verbose(`Config path: ${opts.configPath || "default"}`);
+    logger.verbose(`Overwrite mode: ${config.overwrite ? "enabled" : "disabled"}`);
     const generatesArray = Array.isArray(config.generates) ? config.generates : [config.generates];
+    logger.verbose(`Found ${generatesArray.length} generate configuration(s)`);
     for (const urlSchema of generatesArray) {
       for (const [filePath, generatorConfig] of Object.entries(urlSchema)) {
         try {
-          await fetchAlgoliaData(filePath, generatorConfig, config.overwrite);
+          await fetchAlgoliaData(filePath, generatorConfig, config.overwrite, logger);
         } catch (error) {
-          console.error(`
-Error processing file: ${filePath}`);
-          if (error instanceof Error) {
-            console.error(error.message);
-            if (error.stack) {
-              console.error(error.stack);
-            }
-          } else {
-            try {
-              console.error(JSON.stringify(error, null, 2));
-            } catch {
-              console.error(String(error));
-            }
-          }
+          logger.error(`Error processing file: ${filePath}`);
+          const errorMessage = logger.formatError(error, "Processing failed");
+          logger.error(errorMessage);
         }
       }
     }
-  } catch (error) {
-    console.error("Error loading config:");
-    if (error instanceof Error) {
-      console.error(error.message);
+    if (opts.dryRun) {
+      logger.info("Dry-run completed. No files were written.");
     } else {
-      console.error(String(error));
+      logger.success("All files generated successfully!");
     }
+  } catch (error) {
+    logger.error("Failed to load configuration");
+    const errorMessage = logger.formatError(error, "Configuration error");
+    logger.error(errorMessage);
     process.exit(1);
   }
 };