@intlayer/config 1.0.2 → 1.2.1

package/src/types/config.ts

@@ -1,64 +1,121 @@
 import type { Locales } from './locales';
 
+/**
+ * Configuration for internationalization settings
+ */
 export type InternationalizationConfig = {
-  // Available languages in the app
-  locales: Locales[]; // default [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH]
+  /**
+   * Locales available in the application
+   *
+   * Default: [Locales.ENGLISH]
+   *
+   * You can define a list of available locales to support in the application.
+   */
+  locales: Locales[];
 
-  // Default language
-  defaultLocale: Locales; // default Locales.ENGLISH
+  /**
+   * Default locale of the application for fallback
+   *
+   * Default: Locales.ENGLISH
+   *
+   * Used to specify a fallback locale in case no other locale is set.
+   */
+  defaultLocale: Locales;
 };
 
 export type ServerSetCookieRule = 'always' | 'never';
+
+/**
+ * Configuration for middleware behaviors
+ */
 export type MiddlewareConfig = {
-  // Header name to get the language
-  headerName: string; // default 'x-intlayer-locale'
+  /**
+   * Header name to get the locale from the request
+   *
+   * Default: 'x-intlayer-locale'
+   *
+   * The HTTP header key used to determine the current locale.
+   */
+  headerName: string;
 
-  // Cookie name to get the language
-  cookieName: string; // default 'NEXT_LOCALE'
+  /**
+   * Cookie name to store the locale information
+   *
+   * Default: 'NEXT_LOCALE'
+   *
+   * The cookie key where the locale information is stored.
+   */
+  cookieName: string;
 
-  // Prefix the default language in the URL
-  prefixDefault: boolean; // default false
+  /**
+   * Whether to prefix the default locale in the URL
+   *
+   * Default: false
+   *
+   * When set to true, the default locale is prefixed in the URL for localization purposes.
+   */
+  prefixDefault: boolean;
 
-  // Base path
-  basePath: string; // default ''
+  /**
+   * Base path for application URLs
+   *
+   * Default: ''
+   *
+   * Defines the base path where the application is accessible from.
+   */
+  basePath: string;
 
-  // Set cookie on server
-  serverSetCookie: ServerSetCookieRule; // default 'always'
+  /**
+   * Strategy for setting the locale cookie on the server
+   *
+   * Default: 'always'
+   *
+   * This setting controls when the server sets the locale cookie. It can either set the cookie on every request or never set it.
+   */
+  serverSetCookie: ServerSetCookieRule;
 
-  // No prefix
-  noPrefix: boolean; // default false;
+  /**
+   * Indicates if no prefix should be used in the URL for locale
+   *
+   * Default: false
+   *
+   * If true, no locale-based prefix is used in the URL.
+   */
+  noPrefix: boolean;
 };
 
+/**
+ * Custom configuration that can be provided to override default settings
+ */
 export type CustomIntlayerConfig = {
   /**
-   * Internationalization configuration
+   * Custom internationalization configuration
    */
-
   internationalization?: Partial<InternationalizationConfig>;
 
   /**
-   * Middleware configuration
+   * Custom middleware configuration
    */
-
   middleware?: Partial<MiddlewareConfig>;
 
   /**
-   * Content configuration
+   * Custom content configuration
    */
   content?: Partial<ContentConfig>;
 };
 
+/**
+ * Combined configuration for internationalization, middleware, and content
+ */
 export type IntlayerConfig = {
   /**
    * Internationalization configuration
    */
-
   internationalization: InternationalizationConfig;
 
   /**
    * Middleware configuration
    */
-
   middleware: MiddlewareConfig;
 
   /**
@@ -67,77 +124,236 @@ export type IntlayerConfig = {
   content: ContentConfig;
 };
 
+/**
+ * Base configuration for content handling
+ */
 export type BaseContentConfig = {
-  // File extensions of content to look for
-  fileExtensions: string[]; // default ['.content.ts', '.content.js', '.content.json']
-
-  // Directory of the project
-  baseDir: string; // default process.cwd()
+  /**
+   * File extensions of content to look for
+   *
+   * Default: ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
+   *
+   * List of file extensions to scan for content.
+   */
+  fileExtensions: string[];
 
-  // Directory name where the content is stored
-  contentDirName: string; // default 'src'
+  /**
+   * Absolute path of the project's base directory
+   *
+   * Default: process.cwd()
+   *
+   * The root directory of the project, typically used for resolving other paths.
+   */
+  baseDir: string;
 
-  // Directories to exclude
-  excludedPath: string[]; // default ['node_modules']
+  /**
+   * Name of the directory where the content is stored
+   *
+   * Default: 'src'
+   *
+   * Specifies the directory where the primary content is stored.
+   */
+  contentDirName: string;
 
-  // Result directory name
-  resultDirName: string; // default '.intlayer'
+  /**
+   * Directories to be excluded from content processing
+   *
+   * Default: ['node_modules']
+   *
+   * A list of directories to exclude from content processing.
+   */
+  excludedPath: string[];
 
-  // Module augmentation directory name
-  moduleAugmentationDirName: string; // default 'types'
+  /**
+   * Name of the directory where results are stored
+   *
+   * Default: '.intlayer'
+   *
+   * The directory for storing intermediate or output results.
+   */
+  resultDirName: string;
 
-  // Bundle directory name
-  bundleDirName: string; // default 'bundle'
+  /**
+   * Name of the directory for module augmentation
+   *
+   * Default: 'types'
+   *
+   * Defines the directory for additional module types.
+   */
+  moduleAugmentationDirName: string;
 
-  // Bundle file extension
-  bundleFileExtension: string; // default '.bundle.js'
+  /**
+   * Name of the directory where dictionaries are stored
+   *
+   * Default: 'dictionary'
+   *
+   * The directory for storing localization dictionaries.
+   *
+   * Note:
+   * - Ensure the dictionaries output includes intlayer to build the dictionaries for intlayer
+   */
+  dictionariesDirName: string;
 
-  // Dictionary directory name
-  dictionariesDirName: string; // default 'dictionary'
+  /**
+   * Name of the directory where dictionaries are stored
+   *
+   * Default: 'i18n_dictionary'
+   *
+   * The directory for storing localization dictionaries.
+   *
+   * Note:
+   * - Ensure the dictionaries output includes 'i18next' to build the dictionaries for i18next
+   */
+  i18nDictionariesDirName: string;
 
-  // Types directory name
-  typeDirName: string; // default 'types'
+  /**
+   * Name of the directory where dictionary types are stored
+   *
+   * Default: 'types'
+   *
+   * The directory for storing dictionary type definitions.
+   */
+  typeDirName: string;
 
-  // Main directory name
-  mainDirName: string; // default 'main'
+  /**
+   * Name of the directory where the main files are stored
+   *
+   * Default: 'main'
+   *
+   * Specifies the directory for storing main application files.
+   */
+  mainDirName: string;
 };
 
+export type DictionaryOutput = 'intlayer' | 'i18next';
+
+/**
+ * Configuration derived based on the base content configuration
+ */
 export type BaseDerivedConfig = {
-  // Directory to watch - emplacement where the content is stored
-  contentDir: string; // default {{baseDir}} / {{contentDirName}}
+  /**
+   * Directory where the content is stored, relative to the base directory
+   *
+   * Default: {{baseDir}} / {{contentDirName}}
+   *
+   * Derived content directory based on the base configuration.
+   */
+  contentDir: string;
 
-  // Result directory
-  resultDir: string; // default {{baseDir}} / {{resultDirName}}
+  /**
+   * Directory where the results are stored, relative to the base directory
+   *
+   * Default: {{baseDir}} / {{resultDirName}}
+   *
+   * Derived results directory based on the base configuration.
+   */
+  resultDir: string;
+
+  /**
+   * Directory for module augmentation, relative to the base directory
+   *
+   * Default: {{baseDir}} / {{moduleAugmentationDirName}}
+   *
+   * Defines the derived path for module augmentation.
+   */
+  moduleAugmentationDir: string;
 
-  // Result directory
-  moduleAugmentationDir: string; // default {{baseDir}} / {{moduleAugmentationDirName}}
+  /**
+   * Type of dictionary to use as an output
+   *
+   * Default: ['intlayer']
+   *
+   * The type of dictionary to use as an output. It can be either 'intlayer' or 'i18next'.
+   *
+   * Note:
+   * - 'i18next' is not yet ensure a 1:1 mapping with the i18next library.
+   * - Removing 'intlayer' will break the compatibility with react-intlayer or next-intlayer
+   *
+   */
+  dictionaryOutput: DictionaryOutput[];
 };
 
+/**
+ * Configuration derived based on the result directory
+ */
 export type ResultDirDerivedConfig = {
-  // Bundle directory
-  bundleDir: string; // default {{resultDir}} / {{bundleDirName}}
+  /**
+   * Directory where dictionaries are stored, relative to the result directory
+   *
+   * Default: {{resultDir}} / {{dictionariesDirName}}
+   *
+   * Specifies the derived path for dictionaries relative to the result directory.
+   */
+  dictionariesDir: string;
 
-  // Dictionary directory
-  dictionariesDir: string; // default {{resultDir}} / {{dictionaryDirName}}
+  /**
+   *
+   * Directory where dictionaries are stored, relative to the result directory
+   *
+   * Default: {{resultDir}} / {{i18nDictionariesDirName}}
+   *
+   * Specifies the derived path for dictionaries relative to the result directory.
+   *
+   * Note:
+   * - Ensure the i18n dictionaries output includes i18next to build the dictionaries for i18next
+   */
+  i18nDictionariesDir: string;
 
-  // Types directory
-  typesDir: string; // default {{resultDir}} / {{typeDirName}}
+  /**
+   * Directory where dictionary types are stored, relative to the result directory
+   *
+   * Default: {{resultDir}} / {{typeDirName}}
+   *
+   * Specifies the derived path for dictionary types relative to the result directory.
+   */
+  typesDir: string;
 
-  // Main directory
-  mainDir: string; // default {{resultDir}} / {{mainDirName}}
+  /**
+   * Directory where the main files are stored, relative to the result directory
+   *
+   * Default: {{resultDir}} / {{mainDirName}}
+   *
+   * Specifies the derived path for the main files relative to the result directory.
+   */
+  mainDir: string;
 };
 
+/**
+ * Configuration for content patterns
+ */
 export type PatternsContentConfig = {
-  // Pattern of files to watch
+  /**
+   * Patterns of files to watch for changes
+   *
+   * Default: ['/**\/*.content.ts', '/**\/*.content.js', '/**\/*.content.json', '/**\/*.content.cjs', '/**\/*.content.mjs', '/**\/*.content.tsx', '/**\/*.content.jsx']
+   *
+   * Defines file patterns for content to watch for changes.
+   */
   watchedFilesPattern: string[];
 
-  // Pattern of files to watch including the relative path
+  /**
+   * Patterns of files to watch for changes including the relative path
+   *
+   * Default: ['{{contentDir}}/**\/*.content.ts', '{{contentDir}}/**\/*.content.js', '{{contentDir}}/**\/*.content.json', '{{contentDir}}/**\/*.content.cjs', '{{contentDir}}/**\/*.content.mjs', '{{contentDir}}/**\/*.content.tsx', '{{contentDir}}/**\/*.content.jsx']
+   *
+   * Specifies the file patterns for content to watch, including relative paths.
+   */
   watchedFilesPatternWithPath: string[];
 
-  // Pattern of files to output
+  /**
+   * Pattern for output files including the relative path
+   *
+   * Default: '{{dictionariesDir}}/**\/*.json'
+   *
+   * Defines the pattern for output files, including the relative path.
+   */
   outputFilesPatternWithPath: string;
 };
 
+// @TODO: Implement exclusion of non configurable fields, to not allow them to be set in the config
+/**
+ * General configuration derived from the config file
+ */
 export type ContentConfig = BaseContentConfig &
   BaseDerivedConfig &
   ResultDirDerivedConfig &