feat: provide a API for users to process log message in pnpm-sync-lib

packages/pnpm-sync-lib/etc/pnpm-sync-lib.api.md

@@ -28,6 +28,40 @@ export interface ILockfileImporter {
     optionalDependencies?: Record<string, IVersionSpecifier>;
 }
 
+// @beta (undocumented)
+export interface ILogMessageCallbackOptions {
+    // (undocumented)
+    details: {
+        messageIdentifier: LogMessageIdentifier.PREPARE_STARTING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_PROCESSING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_FINISHING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+        executionTimeInMs: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.COPY_STARTING;
+        pnpmSyncJsonPath: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.COPY_PROCESSING;
+        pnpmSyncJsonPath: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.COPY_FINISHING;
+        pnpmSyncJsonPath: string;
+        fileCount: number;
+        executionTimeInMs: string;
+    };
+    // (undocumented)
+    message: string;
+    // (undocumented)
+    messageKind: LogMessageKind;
+}
+
 // @beta (undocumented)
 export interface IPnpmSyncCopyOptions {
     // (undocumented)
@@ -39,6 +73,8 @@ export interface IPnpmSyncCopyOptions {
     // (undocumented)
     getPackageIncludedFiles: (packagePath: string) => Promise<string[]>;
     // (undocumented)
+    logMessageCallback: (options: ILogMessageCallbackOptions) => void;
+    // (undocumented)
     pnpmSyncJsonPath?: string;
 }
 
@@ -47,6 +83,8 @@ export interface IPnpmSyncPrepareOptions {
     // (undocumented)
     lockfilePath: string;
     // (undocumented)
+    logMessageCallback: (options: ILogMessageCallbackOptions) => void;
+    // (undocumented)
     readPnpmLockfile: (lockfilePath: string, options: {
         ignoreIncompatible: boolean;
     }) => Promise<ILockfile | undefined>;
@@ -59,10 +97,38 @@ export type IVersionSpecifier = string | {
     version: string;
 };
 
+// @beta (undocumented)
+export enum LogMessageIdentifier {
+    // (undocumented)
+    COPY_FINISHING = "Finishing pnpm-sync copy",
+    // (undocumented)
+    COPY_PROCESSING = "Processing pnpm-sync copy",
+    // (undocumented)
+    COPY_STARTING = "Starting pnpm-sync copy",
+    // (undocumented)
+    PREPARE_FINISHING = "Finishing pnpm-sync prepare",
+    // (undocumented)
+    PREPARE_PROCESSING = "Processing pnpm-sync prepare",
+    // (undocumented)
+    PREPARE_STARTING = "Starting pnpm-sync prepare"
+}
+
+// @beta (undocumented)
+export enum LogMessageKind {
+    // (undocumented)
+    ERROR = "error",
+    // (undocumented)
+    INFO = "info",
+    // (undocumented)
+    VERBOSE = "verbose",
+    // (undocumented)
+    WARNING = "warning"
+}
+
 // @beta
-export function pnpmSyncCopyAsync({ pnpmSyncJsonPath, getPackageIncludedFiles, forEachAsyncWithConcurrency, ensureFolder }: IPnpmSyncCopyOptions): Promise<void>;
+export function pnpmSyncCopyAsync({ pnpmSyncJsonPath, getPackageIncludedFiles, forEachAsyncWithConcurrency, ensureFolder, logMessageCallback }: IPnpmSyncCopyOptions): Promise<void>;
 
 // @beta
-export function pnpmSyncPrepareAsync({ lockfilePath, storePath, readPnpmLockfile }: IPnpmSyncPrepareOptions): Promise<void>;
+export function pnpmSyncPrepareAsync({ lockfilePath, storePath, readPnpmLockfile, logMessageCallback }: IPnpmSyncPrepareOptions): Promise<void>;
 
 ```

packages/pnpm-sync-lib/src/index.ts

@@ -7,4 +7,11 @@
 
 export { pnpmSyncCopyAsync, type IPnpmSyncCopyOptions } from './pnpmSyncCopy';
 export { pnpmSyncPrepareAsync, type IPnpmSyncPrepareOptions } from './pnpmSyncPrepare';
-export type { ILockfile, ILockfileImporter, IVersionSpecifier, IDependencyMeta } from './interfaces';
+export { LogMessageIdentifier, LogMessageKind } from './interfaces';
+export type {
+  ILockfile,
+  ILockfileImporter,
+  IVersionSpecifier,
+  IDependencyMeta,
+  ILogMessageCallbackOptions
+} from './interfaces';

packages/pnpm-sync-lib/src/interfaces.ts

@@ -15,6 +15,67 @@ export interface ITargetFolder {
   folderPath: string;
 }
 
+/**
+ * @beta
+ */
+export enum LogMessageKind {
+  INFO = 'info',
+  WARNING = 'warning',
+  ERROR = 'error',
+  VERBOSE = 'verbose'
+}
+
+/**
+ * @beta
+ */
+export enum LogMessageIdentifier {
+  PREPARE_STARTING = 'Starting pnpm-sync prepare',
+  PREPARE_PROCESSING = 'Processing pnpm-sync prepare',
+  PREPARE_FINISHING = 'Finishing pnpm-sync prepare',
+  COPY_STARTING = 'Starting pnpm-sync copy',
+  COPY_PROCESSING = 'Processing pnpm-sync copy',
+  COPY_FINISHING = 'Finishing pnpm-sync copy'
+}
+
+/**
+ * @beta
+ */
+export interface ILogMessageCallbackOptions {
+  message: string;
+  messageKind: LogMessageKind;
+  details:
+    | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_STARTING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_PROCESSING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_FINISHING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+        executionTimeInMs: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.COPY_STARTING;
+        pnpmSyncJsonPath: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.COPY_PROCESSING;
+        pnpmSyncJsonPath: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.COPY_FINISHING;
+        pnpmSyncJsonPath: string;
+        fileCount: number;
+        executionTimeInMs: string;
+      };
+}
+
 /**
  * @beta
  */

packages/pnpm-sync-lib/src/pnpmSyncCopy.ts

@@ -1,5 +1,7 @@
 import path from 'path';
 import fs from 'fs';
+import { hrtime } from 'node:process';
+import { ILogMessageCallbackOptions, LogMessageIdentifier, LogMessageKind } from './interfaces';
 
 /**
  * @beta
@@ -13,6 +15,7 @@ export interface IPnpmSyncCopyOptions {
     options: { concurrency: number }
   ) => Promise<void>;
   ensureFolder: (folderPath: string) => Promise<void>;
+  logMessageCallback: (options: ILogMessageCallbackOptions) => void;
 }
 
 /**
@@ -32,22 +35,39 @@ export async function pnpmSyncCopyAsync({
   pnpmSyncJsonPath = '',
   getPackageIncludedFiles,
   forEachAsyncWithConcurrency,
-  ensureFolder
+  ensureFolder,
+  logMessageCallback
 }: IPnpmSyncCopyOptions): Promise<void> {
   if (pnpmSyncJsonPath === '') {
     // if user does not input .pnpm-sync.json file path
     // then we assume .pnpm-sync.json is always under node_modules folder
     pnpmSyncJsonPath = 'node_modules/.pnpm-sync.json';
   }
 
+  logMessageCallback({
+    message: `pnpm-sync copy: Starting operation...`,
+    messageKind: LogMessageKind.VERBOSE,
+    details: {
+      messageIdentifier: LogMessageIdentifier.COPY_STARTING,
+      pnpmSyncJsonPath
+    }
+  });
+
   let pnpmSyncJsonContents: string;
   try {
     pnpmSyncJsonContents = (await fs.promises.readFile(pnpmSyncJsonPath)).toString();
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
-      console.warn(
-        'You are executing pnpm-sync for a package, but we can not find the .pnpm-sync.json inside node_modules folder'
-      );
+      logMessageCallback({
+        message:
+          'You are executing pnpm-sync for a package, but we can not find the .pnpm-sync.json inside node_modules folder',
+        messageKind: LogMessageKind.ERROR,
+        details: {
+          messageIdentifier: LogMessageIdentifier.COPY_PROCESSING,
+          pnpmSyncJsonPath
+        }
+      });
+
       return;
     } else {
       throw e;
@@ -62,7 +82,7 @@ export async function pnpmSyncCopyAsync({
   //get npmPackFiles
   const npmPackFiles: string[] = await getPackageIncludedFiles(sourcePath);
 
-  console.time(`pnpm-sync => ${sourcePath}, total ${npmPackFiles.length} files`);
+  const startTime = hrtime.bigint();
 
   //clear the destination folder first
   for (const targetFolder of targetFolders) {
@@ -90,5 +110,18 @@ export async function pnpmSyncCopyAsync({
     }
   );
 
-  console.timeEnd(`pnpm-sync => ${sourcePath}, total ${npmPackFiles.length} files`);
+  const endTime = hrtime.bigint();
+  const copyExecutionTimeInMs: string = (Number(endTime - startTime) / 1e6).toFixed(3) + 'ms';
+  const infoMessage = `pnpm-sync copy: Copied ${npmPackFiles.length} files in ${copyExecutionTimeInMs} from ${sourcePath}`;
+
+  logMessageCallback({
+    message: infoMessage,
+    messageKind: LogMessageKind.INFO,
+    details: {
+      messageIdentifier: LogMessageIdentifier.COPY_FINISHING,
+      pnpmSyncJsonPath,
+      fileCount: npmPackFiles.length,
+      executionTimeInMs: copyExecutionTimeInMs
+    }
+  });
 }

packages/pnpm-sync-lib/src/pnpmSyncPrepare.ts

@@ -1,8 +1,15 @@
 import path from 'path';
 import fs from 'fs';
-import { cwd } from 'process';
+import { cwd, hrtime } from 'process';
 
-import type { ILockfile, IPnpmSyncJson, IVersionSpecifier } from './interfaces';
+import {
+  ILockfile,
+  ILogMessageCallbackOptions,
+  LogMessageKind,
+  LogMessageIdentifier,
+  IPnpmSyncJson,
+  IVersionSpecifier
+} from './interfaces';
 
 /**
  * @beta
@@ -14,6 +21,7 @@ export interface IPnpmSyncPrepareOptions {
     lockfilePath: string,
     options: { ignoreIncompatible: boolean }
   ) => Promise<ILockfile | undefined>;
+  logMessageCallback: (options: ILogMessageCallbackOptions) => void;
 }
 
 /**
@@ -30,22 +38,31 @@ export interface IPnpmSyncPrepareOptions {
 export async function pnpmSyncPrepareAsync({
   lockfilePath,
   storePath,
-  readPnpmLockfile
+  readPnpmLockfile,
+  logMessageCallback
 }: IPnpmSyncPrepareOptions): Promise<void> {
-  console.log('Generate pnpm-sync.json ...');
-
   // get the pnpm-lock.yaml path
   lockfilePath = path.resolve(cwd(), lockfilePath);
   storePath = path.resolve(cwd(), storePath);
 
-  console.log('The pnpm-lock.yaml file path =>', lockfilePath);
-  console.log('The .pnpm folder path =>', storePath);
+  logMessageCallback({
+    message:
+      `pnpm-sync prepare: Starting operation...\n` +
+      `pnpm-sync prepare: The pnpm-lock.yaml file path => ${lockfilePath}\n` +
+      `pnpm-sync prepare: The .pnpm folder path => ${storePath}`,
+    messageKind: LogMessageKind.VERBOSE,
+    details: {
+      messageIdentifier: LogMessageIdentifier.PREPARE_STARTING,
+      lockfilePath,
+      dotPnpmFolderPath: storePath
+    }
+  });
 
   if (!fs.existsSync(lockfilePath)) {
     throw Error('The input pnpm-lock.yaml path is not correct!');
   }
 
-  console.time(`pnpm-sync prepare`);
+  const startTime = hrtime.bigint();
 
   // read the pnpm-lock.yaml
   const pnpmLockfile = await readPnpmLockfile(lockfilePath, {
@@ -119,7 +136,20 @@ export async function pnpmSyncPrepareAsync({
     }
     fs.writeFileSync(pnpmSyncJsonPath, JSON.stringify(pnpmSyncJsonFile, null, 2));
   }
-  console.timeEnd(`pnpm-sync prepare`);
+
+  const endTime = hrtime.bigint();
+  const prepareExecutionTimeInMs: string = (Number(endTime - startTime) / 1e6).toFixed(3) + 'ms';
+
+  logMessageCallback({
+    message: `pnpm-sync prepare: Regenerated pnpm-sync.json in ${prepareExecutionTimeInMs} for ${lockfilePath}`,
+    messageKind: LogMessageKind.INFO,
+    details: {
+      messageIdentifier: LogMessageIdentifier.PREPARE_FINISHING,
+      lockfilePath,
+      dotPnpmFolderPath: storePath,
+      executionTimeInMs: prepareExecutionTimeInMs
+    }
+  });
 }
 
 function transferFilePathToPnpmStorePath(