@napi-rs/cli 3.6.1 → 3.7.0

package/src/utils/config.ts

@@ -42,6 +42,11 @@ export interface UserNapiConfig {
    */
   constEnum?: boolean
 
+  /**
+   * Emit `#[napi(string_enum)]` enums as runtime enums (`export declare enum`) under `--no-const-enum`. Default: type-only union.
+   */
+  runtimeStringEnum?: boolean
+
   /**
    * dts header prepend to the generated dts file
    */
@@ -155,7 +160,10 @@ export interface CommonPackageJsonFields {
 export type NapiConfig = Required<
   Pick<UserNapiConfig, 'binaryName' | 'packageName' | 'npmClient'>
 > &
-  Pick<UserNapiConfig, 'wasm' | 'dtsHeader' | 'dtsHeaderFile' | 'constEnum'> & {
+  Pick<
+    UserNapiConfig,
+    'wasm' | 'dtsHeader' | 'dtsHeaderFile' | 'constEnum' | 'runtimeStringEnum'
+  > & {
     targets: Target[]
     packageJson: CommonPackageJsonFields
   }

package/src/utils/misc.ts

@@ -43,6 +43,27 @@ export function pick<O, K extends keyof O>(o: O, ...keys: K[]): Pick<O, K> {
   }, {} as O)
 }
 
+function isPlainObject(value: unknown): value is Record<string, any> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function mergePackageJson(
+  old: Record<string, any>,
+  partial: Record<string, any>,
+): Record<string, any> {
+  const merged = { ...old }
+
+  for (const [key, value] of Object.entries(partial)) {
+    if (isPlainObject(merged[key]) && isPlainObject(value)) {
+      merged[key] = mergePackageJson(merged[key], value)
+    } else {
+      merged[key] = value
+    }
+  }
+
+  return merged
+}
+
 export async function updatePackageJson(
   path: string,
   partial: Record<string, any>,
@@ -53,7 +74,10 @@ export async function updatePackageJson(
     return
   }
   const old = JSON.parse(await readFileAsync(path, 'utf8'))
-  await writeFileAsync(path, JSON.stringify({ ...old, ...partial }, null, 2))
+  await writeFileAsync(
+    path,
+    JSON.stringify(mergePackageJson(old, partial), null, 2),
+  )
 }
 
 export const CLI_VERSION = pkgJson.version

package/src/utils/typegen.ts

@@ -29,9 +29,26 @@ interface TypeDefLine {
   js_mod?: string
 }
 
+/**
+ * Render a single intermediate type-def line as the TypeScript source it
+ * should produce in `index.d.ts`.
+ *
+ * @param line - The intermediate type-def entry to render.
+ * @param constEnum - When true, emit numeric and string `#[napi]` enums as
+ *   `const enum`. When false (`--no-const-enum`), numeric enums become
+ *   regular runtime enums and string enums fall back to a type-only union
+ *   unless `runtimeStringEnum` is also true.
+ * @param runtimeStringEnum - When true under `--no-const-enum`, emit
+ *   `#[napi(string_enum)]` as a runtime enum (`export declare enum`)
+ *   instead of a type-only union. No-op when `constEnum` is true.
+ * @param ident - Indentation level applied to the rendered output.
+ * @param ambient - When true, emit declarations in the ambient form used
+ *   inside `declare namespace` blocks (e.g. drop the `declare` keyword).
+ */
 function prettyPrint(
   line: TypeDefLine,
   constEnum: boolean,
+  runtimeStringEnum: boolean,
   ident: number,
   ambient = false,
 ): string {
@@ -45,18 +62,22 @@ function prettyPrint(
       s += `export type ${line.name} = \n${line.def}`
       break
 
-    case TypeDefKind.Enum:
+    case TypeDefKind.Enum: {
       const enumName = constEnum ? 'const enum' : 'enum'
       s += `${exportDeclare(ambient)} ${enumName} ${line.name} {\n${line.def}\n}`
       break
+    }
 
-    case TypeDefKind.StringEnum:
+    case TypeDefKind.StringEnum: {
       if (constEnum) {
         s += `${exportDeclare(ambient)} const enum ${line.name} {\n${line.def}\n}`
+      } else if (runtimeStringEnum) {
+        s += `${exportDeclare(ambient)} enum ${line.name} {\n${line.def}\n}`
       } else {
         s += `export type ${line.name} = ${line.def.replaceAll(/.*=/g, '').replaceAll(',', '|')};`
       }
       break
+    }
 
     case TypeDefKind.Struct:
       const extendsDef = line.extends ? ` extends ${line.extends}` : ''
@@ -97,9 +118,20 @@ function exportDeclare(ambient: boolean): string {
   return 'export declare'
 }
 
+/**
+ * Read the napi-derive-emitted intermediate type-def file and render its
+ * entries into the `index.d.ts` source string plus the list of names to
+ * re-export from `index.js`.
+ *
+ * @param intermediateTypeFile - Path to the JSONL type-def file produced
+ *   by napi-derive (one entry per `#[napi]` item).
+ * @param constEnum - See {@link prettyPrint}.
+ * @param runtimeStringEnum - See {@link prettyPrint}. Defaults to `false`.
+ */
 export async function processTypeDef(
   intermediateTypeFile: string,
   constEnum: boolean,
+  runtimeStringEnum: boolean = false,
 ) {
   const exports: string[] = []
   const defs = await readIntermediateTypeFile(intermediateTypeFile)
@@ -126,7 +158,7 @@ export async function processTypeDef(
                 default:
                   break
               }
-              return prettyPrint(def, constEnum, 0)
+              return prettyPrint(def, constEnum, runtimeStringEnum, 0)
             })
             .join('\n\n')
         } else {
@@ -134,7 +166,8 @@ export async function processTypeDef(
           let declaration = ''
           declaration += `export declare namespace ${namespace} {\n`
           for (const def of defs) {
-            declaration += prettyPrint(def, constEnum, 2, true) + '\n'
+            declaration +=
+              prettyPrint(def, constEnum, runtimeStringEnum, 2, true) + '\n'
           }
           declaration += '}'
           return declaration

package/src/utils/version.ts

@@ -25,6 +25,10 @@ const NAPI_VERSION_MATRIX = new Map<NapiVersion, string>([
   [NapiVersion.Napi9, '18.17.0 | 20.3.0 | 21.1.0'],
 ])
 
+export const SUPPORTED_NAPI_VERSIONS = Object.values(NapiVersion).filter(
+  (v): v is NapiVersion => typeof v === 'number',
+)
+
 interface NodeVersion {
   major: number
   minor: number