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,18 @@ export interface ILockfileImporter {
     optionalDependencies?: Record<string, IVersionSpecifier>;
 }
 
+// @beta (undocumented)
+export enum ILogMessageKind {
+    // (undocumented)
+    ERROR = "error",
+    // (undocumented)
+    INFO = "info",
+    // (undocumented)
+    VERBOSE = "verbose",
+    // (undocumented)
+    WARNING = "warning"
+}
+
 // @beta (undocumented)
 export interface IPnpmSyncCopyOptions {
     // (undocumented)
@@ -39,6 +51,11 @@ export interface IPnpmSyncCopyOptions {
     // (undocumented)
     getPackageIncludedFiles: (packagePath: string) => Promise<string[]>;
     // (undocumented)
+    logMessageCallback: (message: string, messageKind: ILogMessageKind, details?: {
+        fileCount: number;
+        executionTimeInMs: string;
+    }) => void;
+    // (undocumented)
     pnpmSyncJsonPath?: string;
 }
 
@@ -47,6 +64,12 @@ export interface IPnpmSyncPrepareOptions {
     // (undocumented)
     lockfilePath: string;
     // (undocumented)
+    logMessageCallback: (message: string, messageKind: ILogMessageKind, details?: {
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+        executionTimeInMs: string;
+    }) => void;
+    // (undocumented)
     readPnpmLockfile: (lockfilePath: string, options: {
         ignoreIncompatible: boolean;
     }) => Promise<ILockfile | undefined>;
@@ -60,9 +83,9 @@ export type IVersionSpecifier = string | {
 };
 
 // @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,5 @@
 
 export { pnpmSyncCopyAsync, type IPnpmSyncCopyOptions } from './pnpmSyncCopy';
 export { pnpmSyncPrepareAsync, type IPnpmSyncPrepareOptions } from './pnpmSyncPrepare';
+export { ILogMessageKind } from './interfaces';
 export type { ILockfile, ILockfileImporter, IVersionSpecifier, IDependencyMeta } from './interfaces';

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

@@ -15,6 +15,16 @@ export interface ITargetFolder {
   folderPath: string;
 }
 
+/**
+ * @beta
+ */
+export enum ILogMessageKind {
+  INFO = 'info',
+  WARNING = 'warning',
+  ERROR = 'error',
+  VERBOSE = 'verbose'
+}
+
 /**
  * @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 { ILogMessageKind } from './interfaces';
 
 /**
  * @beta
@@ -13,6 +15,14 @@ export interface IPnpmSyncCopyOptions {
     options: { concurrency: number }
   ) => Promise<void>;
   ensureFolder: (folderPath: string) => Promise<void>;
+  logMessageCallback: (
+    message: string,
+    messageKind: ILogMessageKind,
+    details?: {
+      fileCount: number;
+      executionTimeInMs: string;
+    }
+  ) => void;
 }
 
 /**
@@ -32,7 +42,8 @@ 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
@@ -45,9 +56,9 @@ export async function pnpmSyncCopyAsync({
     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'
-      );
+      const errorMessage: string =
+        'You are executing pnpm-sync for a package, but we can not find the .pnpm-sync.json inside node_modules folder';
+      logMessageCallback(errorMessage, ILogMessageKind.ERROR);
       return;
     } else {
       throw e;
@@ -62,7 +73,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 +101,11 @@ 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(infoMessage, ILogMessageKind.INFO, {
+    fileCount: npmPackFiles.length,
+    executionTimeInMs: copyExecutionTimeInMs
+  });
 }

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

@@ -1,8 +1,8 @@
 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, ILogMessageKind, IPnpmSyncJson, IVersionSpecifier } from './interfaces';
 
 /**
  * @beta
@@ -14,6 +14,15 @@ export interface IPnpmSyncPrepareOptions {
     lockfilePath: string,
     options: { ignoreIncompatible: boolean }
   ) => Promise<ILockfile | undefined>;
+  logMessageCallback: (
+    message: string,
+    messageKind: ILogMessageKind,
+    details?: {
+      lockfilePath: string;
+      dotPnpmFolderPath: string;
+      executionTimeInMs: string;
+    }
+  ) => void;
 }
 
 /**
@@ -30,22 +39,24 @@ 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('pnpm-sync prepare: Starting operation...', ILogMessageKind.VERBOSE);
+  logMessageCallback(
+    `pnpm-sync prepare: The pnpm-lock.yaml file path => ${lockfilePath}`,
+    ILogMessageKind.VERBOSE
+  );
+  logMessageCallback(`pnpm-sync prepare: The .pnpm folder path => ${storePath}`, ILogMessageKind.VERBOSE);
 
   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 +130,15 @@ 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';
+  const infoMessage = `pnpm-sync prepare: Regenerated pnpm-sync.json in ${prepareExecutionTimeInMs} for ${lockfilePath}`;
+  logMessageCallback(infoMessage, ILogMessageKind.INFO, {
+    lockfilePath,
+    dotPnpmFolderPath: storePath,
+    executionTimeInMs: prepareExecutionTimeInMs
+  });
 }
 
 function transferFilePathToPnpmStorePath(

packages/pnpm-sync/src/start.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { pnpmSyncCopyAsync, pnpmSyncPrepareAsync } from 'pnpm-sync-lib';
+import { pnpmSyncCopyAsync, pnpmSyncPrepareAsync, ILogMessageKind } from 'pnpm-sync-lib';
 import { FileSystem, Async } from '@rushstack/node-core-library';
 import { PackageExtractor } from '@rushstack/package-extractor';
 import { readWantedLockfile, Lockfile } from '@pnpm/lockfile-file';
@@ -16,7 +16,20 @@ program
       await pnpmSyncCopyAsync({
         getPackageIncludedFiles: PackageExtractor.getPackageIncludedFilesAsync,
         forEachAsyncWithConcurrency: Async.forEachAsync,
-        ensureFolder: FileSystem.ensureFolderAsync
+        ensureFolder: FileSystem.ensureFolderAsync,
+        logMessageCallback: (message: string, messageType: ILogMessageKind) => {
+          switch (messageType) {
+            case ILogMessageKind.ERROR:
+              console.error(message);
+              break;
+            case ILogMessageKind.WARNING:
+              console.warn(message);
+              break;
+            default:
+              console.log(message);
+              break;
+          }
+        }
       })
   );
 
@@ -46,6 +59,19 @@ program
           } else {
             return lockfile;
           }
+        },
+        logMessageCallback: (message: string, messageType: ILogMessageKind) => {
+          switch (messageType) {
+            case ILogMessageKind.ERROR:
+              console.error(message);
+              break;
+            case ILogMessageKind.WARNING:
+              console.warn(message);
+              break;
+            default:
+              console.log(message);
+              break;
+          }
         }
       });
     } catch (error) {