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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}