@xndrjs/i18n 0.7.0 → 0.8.0

package/dist/codegen/index.d.ts

@@ -1,79 +1,100 @@
 import { z } from 'zod';
 
-declare const DELIVERY_MODES: readonly ["canonical", "split-by-locale", "custom"];
+declare const DELIVERY_MODES: readonly ["split-by-locale", "custom"];
 type DeliveryMode = (typeof DELIVERY_MODES)[number];
+declare const LOADER_STRATEGIES: readonly ["import", "fetch"];
+type LoaderStrategy = (typeof LOADER_STRATEGIES)[number];
 declare const codegenConfigShape: {
-    dictionary: z.ZodOptional<z.ZodString>;
-    namespaces: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    defaultNamespace: z.ZodOptional<z.ZodString>;
-    typesOutput: z.ZodString;
-    dictionaryOutput: z.ZodOptional<z.ZodString>;
-    instanceOutput: z.ZodString;
-    dictionarySchemaOutput: z.ZodOptional<z.ZodString>;
-    loadOnInit: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    namespaceLoadersOutput: z.ZodOptional<z.ZodString>;
-    importExtension: z.ZodOptional<z.ZodEnum<{
-        none: "none";
-        ".ts": ".ts";
-        ".js": ".js";
-    }>>;
-    paramsTypeName: z.ZodString;
-    schemaTypeName: z.ZodString;
-    localeTypeName: z.ZodOptional<z.ZodString>;
-    localeFallbackConstName: z.ZodOptional<z.ZodString>;
+    /** PascalCase project id — generates `{project}Params`, `{project}Schema`, `{project}Locale`. */
+    projectName: z.ZodString;
+    namespaces: z.ZodRecord<z.ZodString, z.ZodString>;
+    /**
+     * Directory for generated TypeScript modules:
+     * `i18n-types.generated.ts`, `instance.generated.ts`,
+     * `namespace-loaders.generated.ts`, `dictionary-schema.generated.ts`.
+     */
+    codegenPath: z.ZodString;
     localeFallback: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>>;
-    factoryName: z.ZodOptional<z.ZodString>;
     delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         custom: "custom";
-        canonical: "canonical";
         "split-by-locale": "split-by-locale";
     }>>>;
     deliveryArtifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
-    deliveryOutput: z.ZodOptional<z.ZodString>;
+    /** Directory for delivery JSON (`translations/`). Defaults to {@link codegenPath}. */
+    artifactsPath: z.ZodOptional<z.ZodString>;
+    /**
+     * How generated `namespaceLoaders` resolve artifacts.
+     * - `import` (default): dynamic `import()` — JSON is bundled; content updates need a rebuild.
+     * - `fetch`: runtime `fetchImpl({ locale, namespace, area? })` via required `createI18n({ fetchImpl })`.
+     *   Codegen does not know URLs — mapping id → transport is an application concern.
+     */
+    loaderStrategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        import: "import";
+        fetch: "fetch";
+    }>>>;
 };
 declare const codegenConfigKeys: (keyof typeof codegenConfigShape)[];
 declare const codegenConfigSchema: z.ZodObject<{
-    dictionary: z.ZodOptional<z.ZodString>;
-    namespaces: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    defaultNamespace: z.ZodOptional<z.ZodString>;
-    typesOutput: z.ZodString;
-    dictionaryOutput: z.ZodOptional<z.ZodString>;
-    instanceOutput: z.ZodString;
-    dictionarySchemaOutput: z.ZodOptional<z.ZodString>;
-    loadOnInit: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    namespaceLoadersOutput: z.ZodOptional<z.ZodString>;
-    importExtension: z.ZodOptional<z.ZodEnum<{
-        none: "none";
-        ".ts": ".ts";
-        ".js": ".js";
-    }>>;
-    paramsTypeName: z.ZodString;
-    schemaTypeName: z.ZodString;
-    localeTypeName: z.ZodOptional<z.ZodString>;
-    localeFallbackConstName: z.ZodOptional<z.ZodString>;
+    projectName: z.ZodString;
+    namespaces: z.ZodRecord<z.ZodString, z.ZodString>;
+    codegenPath: z.ZodString;
     localeFallback: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>>;
-    factoryName: z.ZodOptional<z.ZodString>;
     delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         custom: "custom";
-        canonical: "canonical";
         "split-by-locale": "split-by-locale";
     }>>>;
     deliveryArtifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
-    deliveryOutput: z.ZodOptional<z.ZodString>;
+    artifactsPath: z.ZodOptional<z.ZodString>;
+    loaderStrategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        import: "import";
+        fetch: "fetch";
+    }>>>;
 }, z.core.$strict>;
 type CodegenConfigInput = z.input<typeof codegenConfigSchema>;
 type CodegenConfig = z.infer<typeof codegenConfigSchema>;
-declare function resolveDeliveryOutputDir(config: Pick<CodegenConfig, "typesOutput" | "deliveryOutput">): string;
-/** Resolved path for dictionary.generated.ts (explicit config or default next to typesOutput). */
-declare function resolveDictionaryOutputPath(config: Pick<CodegenConfig, "typesOutput" | "dictionaryOutput">): string;
-
-type DeliveryArtifactsMap = Record<string, readonly string[]>;
+declare const GENERATED_BASENAMES: {
+    readonly types: "i18n-types.generated.ts";
+    readonly instance: "instance.generated.ts";
+    readonly namespaceLoaders: "namespace-loaders.generated.ts";
+    readonly dictionarySchema: "dictionary-schema.generated.ts";
+};
+declare const DEFAULT_FACTORY_NAME = "createI18n";
+declare const DEFAULT_LOCALE_FALLBACK_CONST_NAME = "LOCALE_FALLBACK";
+/** Derived paths and symbol names from `projectName` + `codegenPath`. */
+interface ResolvedCodegenPaths {
+    codegenPath: string;
+    typesOutput: string;
+    instanceOutput: string;
+    namespaceLoadersOutput: string;
+    dictionarySchemaOutput: string;
+    artifactsPath: string;
+    paramsTypeName: string;
+    schemaTypeName: string;
+    localeTypeName: string;
+    localeFallbackConstName: string;
+    factoryName: string;
+    deliveryAreaTypeName: string;
+}
+declare function resolveCodegenPaths(config: Pick<CodegenConfig, "projectName" | "codegenPath" | "artifactsPath">): ResolvedCodegenPaths;
+declare function resolveArtifactsPath(config: Pick<CodegenConfig, "codegenPath" | "artifactsPath">): string;
+declare function formatCodegenConfigIssues(error: z.ZodError): string;
 
 declare const SUPPORTED_IMPORT_EXTENSIONS: readonly ["none", ".ts", ".js"];
 type SupportedImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
 
-type SetupMode = "single" | "multi";
-declare function buildCodegenConfig(mode: SetupMode, project: string): CodegenConfigInput;
+interface NamespaceEntry {
+    namespace: string;
+    filePath: string;
+}
+
+/** Parses and validates `i18n.codegen.json`; first step of the codegen pipeline. */
+declare function loadConfig(configPath: string): CodegenConfig;
+/** Maps config namespaces to namespace entries. */
+declare function resolveNamespaces(config: CodegenConfig): NamespaceEntry[];
+
+type DeliveryArtifactsMap = Record<string, readonly string[]>;
+
+declare function buildCodegenConfig(project: string): CodegenConfigInput;
 
 declare function inferProjectName(dirName: string): string;
 declare function typeNamesForProject(project: string): {
@@ -84,4 +105,49 @@ declare function typeNamesForProject(project: string): {
 
 declare function writeCodegenConfig(configPath: string, config: CodegenConfigInput): void;
 
-export { type CodegenConfig, type CodegenConfigInput, DELIVERY_MODES, type DeliveryArtifactsMap, type DeliveryMode, SUPPORTED_IMPORT_EXTENSIONS, type SetupMode, type SupportedImportExtension, buildCodegenConfig, codegenConfigKeys, inferProjectName, resolveDeliveryOutputDir, resolveDictionaryOutputPath, typeNamesForProject, writeCodegenConfig };
+type RunCodegenInput = string | {
+    configPath?: string;
+    config?: CodegenConfig;
+    projectRoot?: string;
+    /** When false, skip console.log summaries (default true). */
+    log?: boolean;
+};
+interface RunCodegenResult {
+    projectRoot: string;
+    generatedFiles: string[];
+    compiledFiles: string[];
+}
+/**
+ * Full codegen pipeline: types + instance + loaders + delivery JSON (+ schema).
+ * Run at build time or when the *contract* changes (keys, params, namespaces, locales).
+ * Content-only refreshes (same ICU contract) should use {@link regenerateNamespaces} instead.
+ */
+declare function runCodegen(input?: RunCodegenInput): RunCodegenResult;
+
+interface RegenerateNamespacesInput {
+    /** Namespaces whose delivery JSON should be refreshed from authoring sources. */
+    namespaces: readonly string[];
+    configPath?: string;
+    config?: CodegenConfig;
+    projectRoot?: string;
+    /** When false, skip console.log summaries (default true). */
+    log?: boolean;
+}
+interface RegenerateNamespacesResult {
+    projectRoot: string;
+    compiledFiles: string[];
+    splitPathsByNamespace: Record<string, Record<string, string>>;
+}
+/**
+ * Content-only refresh: re-materialize delivery JSON for selected namespaces from
+ * current authoring files, without rewriting generated TypeScript.
+ *
+ * Must not change the ICU key/param contract established by a prior {@link runCodegen}.
+ * If authoring changed keys or ICU args, this throws — run {@link runCodegen} and ship a release.
+ *
+ * Authoring updates are out of scope for this library (CMS or editors write those files).
+ * End-to-end without app rebuild requires `loaderStrategy: "fetch"`.
+ */
+declare function regenerateNamespaces(input: RegenerateNamespacesInput): RegenerateNamespacesResult;
+
+export { type CodegenConfig, type CodegenConfigInput, DEFAULT_FACTORY_NAME, DEFAULT_LOCALE_FALLBACK_CONST_NAME, DELIVERY_MODES, type DeliveryArtifactsMap, type DeliveryMode, GENERATED_BASENAMES, LOADER_STRATEGIES, type LoaderStrategy, type RegenerateNamespacesInput, type RegenerateNamespacesResult, type ResolvedCodegenPaths, type RunCodegenInput, type RunCodegenResult, SUPPORTED_IMPORT_EXTENSIONS, type SupportedImportExtension, buildCodegenConfig, codegenConfigKeys, formatCodegenConfigIssues, inferProjectName, loadConfig, regenerateNamespaces, resolveArtifactsPath, resolveCodegenPaths, resolveNamespaces, runCodegen, typeNamesForProject, writeCodegenConfig };