chore(nextjs): Improve type safety of #safe-node-apis

.changeset/sharp-suits-lay.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add types to safe-node-apis modules.

packages/nextjs/src/server/fs/utils.ts

@@ -2,31 +2,27 @@
  * Attention: Only import this module when the node runtime is used.
  * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
  */
-// @ts-ignore
 import nodeRuntime from '#safe-node-apis';
 
-const throwMissingFsModule = (module: string) => {
-  throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
-};
-
-const nodeFsOrThrow = () => {
-  if (!nodeRuntime.fs) {
-    throwMissingFsModule('fs');
+// Generic assertion function that acts as a proper type guard
+function assertNotNullable<T>(value: T, moduleName: string): asserts value is NonNullable<T> {
+  if (!value) {
+    throw new Error(`Clerk: ${moduleName} is missing. This is an internal error. Please contact Clerk's support.`);
   }
+}
+
+const nodeFsOrThrow = (): NonNullable<typeof nodeRuntime.fs> => {
+  assertNotNullable(nodeRuntime.fs, 'fs');
   return nodeRuntime.fs;
 };
 
-const nodePathOrThrow = () => {
-  if (!nodeRuntime.path) {
-    throwMissingFsModule('path');
-  }
+const nodePathOrThrow = (): NonNullable<typeof nodeRuntime.path> => {
+  assertNotNullable(nodeRuntime.path, 'path');
   return nodeRuntime.path;
 };
 
-const nodeCwdOrThrow = () => {
-  if (!nodeRuntime.cwd) {
-    throwMissingFsModule('cwd');
-  }
+const nodeCwdOrThrow = (): NonNullable<typeof nodeRuntime.cwd> => {
+  assertNotNullable(nodeRuntime.cwd, 'cwd');
   return nodeRuntime.cwd;
 };
 

packages/nextjs/src/server/keyless-telemetry.ts

@@ -41,21 +41,21 @@ function getTelemetryFlagFilePath(): string {
  *   the event should be fired), false if the file already exists (meaning the event was
  *   already fired) or if there was an error creating the file
  */
-async function tryMarkTelemetryEventAsFired(): Promise<boolean> {
+function tryMarkTelemetryEventAsFired(): boolean {
   try {
     if (canUseKeyless) {
       const { mkdirSync, writeFileSync } = nodeFsOrThrow();
       const flagFilePath = getTelemetryFlagFilePath();
       const flagDirectory = dirname(flagFilePath);
 
       // Ensure the directory exists before attempting to write the file
-      await mkdirSync(flagDirectory, { recursive: true });
+      mkdirSync(flagDirectory, { recursive: true });
 
       const flagData = {
         firedAt: new Date().toISOString(),
         event: EVENT_KEYLESS_ENV_DRIFT_DETECTED,
       };
-      await writeFileSync(flagFilePath, JSON.stringify(flagData, null, 2), { flag: 'wx' });
+      writeFileSync(flagFilePath, JSON.stringify(flagData, null, 2), { flag: 'wx' });
       return true;
     } else {
       return false;
@@ -177,7 +177,7 @@ export async function detectKeylessEnvDrift(): Promise<void> {
       },
     });
 
-    const shouldFireEvent = await tryMarkTelemetryEventAsFired();
+    const shouldFireEvent = tryMarkTelemetryEventAsFired();
 
     if (shouldFireEvent) {
       // Fire drift detected event only if we successfully created the flag

packages/nextjs/src/types/safe-node-apis.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Global type declarations for #safe-node-apis conditional import
+ */
+
+declare module '#safe-node-apis' {
+  import type { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+  import type * as nodePath from 'node:path';
+
+  interface FileSystem {
+    existsSync: typeof existsSync;
+    writeFileSync: typeof writeFileSync;
+    readFileSync: typeof readFileSync;
+    appendFileSync: typeof appendFileSync;
+    mkdirSync: typeof mkdirSync;
+    rmSync: typeof rmSync;
+  }
+
+  interface SafeNodeApis {
+    fs: FileSystem | undefined;
+    path: typeof nodePath | undefined;
+    cwd: (() => string) | undefined;
+  }
+
+  const safeNodeApis: SafeNodeApis;
+  export = safeNodeApis;
+}