Merge pull request #39 from L-Qun/main

Extract the creation of the pnpm-sync.json file for easy reuse by Rush.

Author: octogonz

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

@@ -58,17 +58,27 @@ export interface IPnpmSyncCopyOptions {
 }
 
 // @beta (undocumented)
-export interface IPnpmSyncPrepareOptions {
+export interface IPnpmSyncPrepareOptions extends IPnpmSyncUpdateFileBaseOptions {
     dotPnpmFolder: string;
     ensureFolderAsync: (folderPath: string) => Promise<void>;
-    lockfileId?: string;
     lockfilePath: string;
-    logMessageCallback: (options: ILogMessageCallbackOptions) => void;
     readPnpmLockfile: (lockfilePath: string, options: {
         ignoreIncompatible: boolean;
     }) => Promise<ILockfile | undefined>;
 }
 
+// @beta (undocumented)
+export interface IPnpmSyncUpdateFileBaseOptions {
+    lockfileId?: string;
+    logMessageCallback: (options: ILogMessageCallbackOptions) => void;
+}
+
+// @beta (undocumented)
+export interface IPnpmSyncUpdateFileOptions extends IPnpmSyncUpdateFileBaseOptions {
+    sourceProjectFolder: string;
+    targetFolders: Array<string>;
+}
+
 // @beta (undocumented)
 export type IVersionSpecifier = string | {
     specifier: string;
@@ -95,13 +105,13 @@ export type LogMessageDetails = {
 } | {
     messageIdentifier: LogMessageIdentifier.PREPARE_REPLACING_FILE;
     pnpmSyncJsonPath: string;
-    projectFolder: string;
+    sourceProjectFolder: string;
     actualVersion: string;
     expectedVersion: string;
 } | {
     messageIdentifier: LogMessageIdentifier.PREPARE_WRITING_FILE;
     pnpmSyncJsonPath: string;
-    projectFolder: string;
+    sourceProjectFolder: string;
 } | {
     messageIdentifier: LogMessageIdentifier.PREPARE_FINISHING;
     lockfilePath: string;
@@ -173,4 +183,7 @@ export function pnpmSyncGetJsonVersion(): string;
 // @beta
 export function pnpmSyncPrepareAsync(options: IPnpmSyncPrepareOptions): Promise<void>;
 
+// @beta (undocumented)
+export function pnpmSyncUpdateFileAsync(options: IPnpmSyncUpdateFileOptions): Promise<void>;
+
 ```

packages/pnpm-sync-lib/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pnpm-sync-lib",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "API library for integrating \"pnpm-sync\" with your toolchain",
   "repository": {
     "type": "git",

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

@@ -6,7 +6,13 @@
  */
 
 export { pnpmSyncCopyAsync, type IPnpmSyncCopyOptions } from './pnpmSyncCopy';
-export { pnpmSyncPrepareAsync, type IPnpmSyncPrepareOptions } from './pnpmSyncPrepare';
+export {
+  pnpmSyncPrepareAsync,
+  pnpmSyncUpdateFileAsync,
+  type IPnpmSyncUpdateFileBaseOptions,
+  type IPnpmSyncPrepareOptions,
+  type IPnpmSyncUpdateFileOptions
+} from './pnpmSyncPrepare';
 export { LogMessageIdentifier, LogMessageKind, LogMessageDetails } from './interfaces';
 export { pnpmSyncGetJsonVersion } from './utilities';
 export type {

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

@@ -80,14 +80,14 @@ export type LogMessageDetails =
   | {
       messageIdentifier: LogMessageIdentifier.PREPARE_REPLACING_FILE;
       pnpmSyncJsonPath: string;
-      projectFolder: string;
+      sourceProjectFolder: string;
       actualVersion: string;
       expectedVersion: string;
     }
   | {
       messageIdentifier: LogMessageIdentifier.PREPARE_WRITING_FILE;
       pnpmSyncJsonPath: string;
-      projectFolder: string;
+      sourceProjectFolder: string;
     }
   | {
       messageIdentifier: LogMessageIdentifier.PREPARE_FINISHING;

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

@@ -19,7 +19,26 @@ import { pnpmSyncGetJsonVersion } from './utilities';
 /**
  * @beta
  */
-export interface IPnpmSyncPrepareOptions {
+export interface IPnpmSyncUpdateFileBaseOptions {
+  /**
+   * A lockfileId that can be used to recognize the `pnpm-lock.yaml`
+   */
+  lockfileId?: string;
+
+  /**
+   * A callback for reporting events during the operation.
+   *
+   * @remarks
+   * `LogMessageKind.ERROR` events do NOT cause the promise to reject,
+   * so they must be handled appropriately.
+   */
+  logMessageCallback: (options: ILogMessageCallbackOptions) => void;
+}
+
+/**
+ * @beta
+ */
+export interface IPnpmSyncPrepareOptions extends IPnpmSyncUpdateFileBaseOptions {
   /**
    * The path to the `pnpm-lock.yaml` file
    */
@@ -30,11 +49,6 @@ export interface IPnpmSyncPrepareOptions {
    */
   dotPnpmFolder: string;
 
-  /**
-   * A lockfileId that can be used to recognize the `pnpm-lock.yaml`
-   */
-  lockfileId?: string;
-
   /**
    * Environment-provided API to avoid an NPM dependency.
    * The "pnpm-sync" NPM package provides a reference implementation.
@@ -49,15 +63,121 @@ export interface IPnpmSyncPrepareOptions {
     lockfilePath: string,
     options: { ignoreIncompatible: boolean }
   ) => Promise<ILockfile | undefined>;
+}
 
+/**
+ * @beta
+ */
+export interface IPnpmSyncUpdateFileOptions extends IPnpmSyncUpdateFileBaseOptions {
   /**
-   * A callback for reporting events during the operation.
+   * The folder path of the project whose build outputs will get synced into the node_modules folder
+   * of dependent projects.
+   * @remarks
+   * It be an absolute file path, such as `/path/to/my-library`, which will have a sync file
+   * `/path/to/my-library/node_modules/.pnpm-sync.json`
+   */
+  sourceProjectFolder: string;
+
+  /**
+   * A list of destination folders that `pnpmSyncCopyAsync()` will copy into.
    *
    * @remarks
-   * `LogMessageKind.ERROR` events do NOT cause the promise to reject,
-   * so they must be handled appropriately.
+   * Each string should be an absolute file path to a folder, whose name will generally
+   * be the same as the `sourceProjectFolder`'s directory name.
+   *
+   * For example:
+   * `/path/to/my-workspace/node_modules/.pnpm/my-library@1.2.3/node_modules/my-library`
+   *
+   * When your tool needs to update this set of files, providing the `IPnpmSyncUpdateFileBaseOptions.lockfileId`
+   * will enable `pnpmSyncUpdateFileAsync()` to clear the old target folders from `.pnpm-sync.json`
+   * before adding the new ones.
    */
-  logMessageCallback: (options: ILogMessageCallbackOptions) => void;
+  targetFolders: Array<string>;
+}
+
+/**
+ * @beta
+ */
+export async function pnpmSyncUpdateFileAsync(options: IPnpmSyncUpdateFileOptions): Promise<void> {
+  const { lockfileId, logMessageCallback, sourceProjectFolder, targetFolders } = options;
+
+  const pnpmSyncJsonFolder = `${sourceProjectFolder}/node_modules`;
+  const pnpmSyncJsonPath = `${pnpmSyncJsonFolder}/.pnpm-sync.json`;
+  const expectedPnpmSyncJsonVersion: string = pnpmSyncGetJsonVersion();
+
+  let pnpmSyncJsonFile: IPnpmSyncJson = {
+    version: expectedPnpmSyncJsonVersion,
+    postbuildInjectedCopy: {
+      sourceFolder: '..', // path from pnpmSyncJsonFolder to sourceProjectFolder
+      targetFolders: []
+    }
+  };
+
+  // if .pnpm-sync.json already exists, read it first
+  if (fs.existsSync(pnpmSyncJsonPath)) {
+    let existingPnpmSyncJsonFile: IPnpmSyncJson | undefined;
+    try {
+      existingPnpmSyncJsonFile = JSON.parse(fs.readFileSync(pnpmSyncJsonPath).toString());
+    } catch (e) {
+      // no-catch
+      // Regenerate .pnpm-sync.json when failed to load the current one
+    }
+
+    if (existingPnpmSyncJsonFile) {
+      const actualPnpmSyncJsonVersion: string = existingPnpmSyncJsonFile.version;
+      if (actualPnpmSyncJsonVersion === expectedPnpmSyncJsonVersion) {
+        // If a lockfileId is provided
+        // then all entries with this lockfileId should be deleted
+        // they will be regenerated later
+        if (lockfileId) {
+          const filteredTargetFolders = existingPnpmSyncJsonFile.postbuildInjectedCopy.targetFolders.filter(
+            (targetFolder) => targetFolder?.lockfileId !== lockfileId
+          );
+          existingPnpmSyncJsonFile.postbuildInjectedCopy.targetFolders = filteredTargetFolders;
+        }
+        pnpmSyncJsonFile = existingPnpmSyncJsonFile;
+      } else {
+        logMessageCallback({
+          message: `The .pnpm-sync.json file in ${pnpmSyncJsonFolder} has an incompatible version; pnpm-sync will regenerate it.`,
+          messageKind: LogMessageKind.VERBOSE,
+          details: {
+            messageIdentifier: LogMessageIdentifier.PREPARE_REPLACING_FILE,
+            pnpmSyncJsonPath,
+            sourceProjectFolder,
+            actualVersion: actualPnpmSyncJsonVersion,
+            expectedVersion: expectedPnpmSyncJsonVersion
+          }
+        });
+      }
+    }
+  }
+
+  const existingTargetFolderSet: Set<string> = new Set();
+
+  for (const targetFolder of pnpmSyncJsonFile.postbuildInjectedCopy.targetFolders) {
+    existingTargetFolderSet.add(targetFolder.folderPath);
+  }
+
+  for (const targetFolder of targetFolders) {
+    let relativePath: string = path.relative(pnpmSyncJsonFolder, targetFolder);
+
+    // the final path in .pnpm-sync.json will always in posix style
+    relativePath = relativePath.split(path.sep).join(path.posix.sep);
+
+    if (!existingTargetFolderSet.has(relativePath)) {
+      const targetFolderItem: ITargetFolder = {
+        folderPath: relativePath
+      };
+
+      if (lockfileId) {
+        targetFolderItem.lockfileId = lockfileId;
+      }
+
+      pnpmSyncJsonFile.postbuildInjectedCopy.targetFolders.push(targetFolderItem);
+    }
+  }
+
+  await fs.promises.writeFile(pnpmSyncJsonPath, JSON.stringify(pnpmSyncJsonFile, null, 2));
 }
 
 /**
@@ -150,7 +270,7 @@ export async function pnpmSyncPrepareAsync(options: IPnpmSyncPrepareOptions): Pr
   const pnpmLockFolder = path.dirname(lockfilePath);
 
   // generate a map, where key is the absolute path of the injectedDependency, value is all available paths in .pnpm folder
-  const injectedDependencyToFilePathSet: Map<string, Set<string>> = new Map();
+  const injectedDependencyToFilePathSet: Map<string, Array<string>> = new Map();
   for (const [injectedDependency, injectedDependencyVersionSet] of injectedDependencyToVersion) {
     for (const injectedDependencyVersion of injectedDependencyVersionSet) {
       // this logic is heavily depends on pnpm-lock formate
@@ -159,7 +279,7 @@ export async function pnpmSyncPrepareAsync(options: IPnpmSyncPrepareOptions): Pr
       let injectedDependencyPath = injectedDependencyVersion.split('(')[0].slice('file:'.length);
       injectedDependencyPath = path.resolve(pnpmLockFolder, injectedDependencyPath);
       if (!injectedDependencyToFilePathSet.has(injectedDependencyPath)) {
-        injectedDependencyToFilePathSet.set(injectedDependencyPath, new Set());
+        injectedDependencyToFilePathSet.set(injectedDependencyPath, []);
       }
 
       const fullPackagePath = path.join(
@@ -169,18 +289,18 @@ export async function pnpmSyncPrepareAsync(options: IPnpmSyncPrepareOptions): Pr
         injectedDependency
       );
 
-      injectedDependencyToFilePathSet.get(injectedDependencyPath)?.add(fullPackagePath);
+      injectedDependencyToFilePathSet.get(injectedDependencyPath)?.push(fullPackagePath);
     }
   }
 
   // now, we have everything we need to generate the the .pnpm-sync.json
   // console.log('injectedDependencyToFilePathSet =>', injectedDependencyToFilePathSet);
-  for (const [projectFolder, targetFolderSet] of injectedDependencyToFilePathSet) {
-    if (targetFolderSet.size === 0) {
+  for (const [sourceProjectFolder, targetFolders] of injectedDependencyToFilePathSet) {
+    if (targetFolders.length === 0) {
       continue;
     }
 
-    const pnpmSyncJsonFolder = `${projectFolder}/node_modules`;
+    const pnpmSyncJsonFolder = `${sourceProjectFolder}/node_modules`;
     const pnpmSyncJsonPath = `${pnpmSyncJsonFolder}/.pnpm-sync.json`;
 
     logMessageCallback({
@@ -189,7 +309,7 @@ export async function pnpmSyncPrepareAsync(options: IPnpmSyncPrepareOptions): Pr
       details: {
         messageIdentifier: LogMessageIdentifier.PREPARE_WRITING_FILE,
         pnpmSyncJsonPath,
-        projectFolder
+        sourceProjectFolder
       }
     });
 
@@ -202,81 +322,12 @@ export async function pnpmSyncPrepareAsync(options: IPnpmSyncPrepareOptions): Pr
       await ensureFolderAsync(pnpmSyncJsonFolder);
     }
 
-    const expectedPnpmSyncJsonVersion: string = pnpmSyncGetJsonVersion();
-
-    let pnpmSyncJsonFile: IPnpmSyncJson = {
-      version: expectedPnpmSyncJsonVersion,
-      postbuildInjectedCopy: {
-        sourceFolder: '..', // path from pnpmSyncJsonFolder to projectFolder
-        targetFolders: []
-      }
-    };
-
-    // if .pnpm-sync.json already exists, read it first
-    if (fs.existsSync(pnpmSyncJsonPath)) {
-      let existingPnpmSyncJsonFile: IPnpmSyncJson | undefined;
-      try {
-        existingPnpmSyncJsonFile = JSON.parse(fs.readFileSync(pnpmSyncJsonPath).toString());
-      } catch (e) {
-        // no-catch
-        // Regenerate .pnpm-sync.json when failed to load the current one
-      }
-
-      if (existingPnpmSyncJsonFile) {
-        const actualPnpmSyncJsonVersion: string = existingPnpmSyncJsonFile.version;
-        if (actualPnpmSyncJsonVersion === expectedPnpmSyncJsonVersion) {
-          // If a lockfileId is provided
-          // then all entries with this lockfileId should be deleted
-          // they will be regenerated later
-          if (lockfileId) {
-            const filteredTargetFolders = existingPnpmSyncJsonFile.postbuildInjectedCopy.targetFolders.filter(
-              (targetFolder) => targetFolder?.lockfileId !== lockfileId
-            );
-            existingPnpmSyncJsonFile.postbuildInjectedCopy.targetFolders = filteredTargetFolders;
-          }
-          pnpmSyncJsonFile = existingPnpmSyncJsonFile;
-        } else {
-          logMessageCallback({
-            message: `The .pnpm-sync.json file in ${pnpmSyncJsonFolder} has an incompatible version; pnpm-sync will regenerate it.`,
-            messageKind: LogMessageKind.VERBOSE,
-            details: {
-              messageIdentifier: LogMessageIdentifier.PREPARE_REPLACING_FILE,
-              pnpmSyncJsonPath,
-              projectFolder,
-              actualVersion: actualPnpmSyncJsonVersion,
-              expectedVersion: expectedPnpmSyncJsonVersion
-            }
-          });
-        }
-      }
-    }
-
-    const existingTargetFolderSet: Set<string> = new Set();
-
-    for (const targetFolder of pnpmSyncJsonFile.postbuildInjectedCopy.targetFolders) {
-      existingTargetFolderSet.add(targetFolder.folderPath);
-    }
-
-    for (const targetFolder of targetFolderSet) {
-      let relativePath: string = path.relative(pnpmSyncJsonFolder, targetFolder);
-
-      // the final path in .pnpm-sync.json will always in posix style
-      relativePath = relativePath.split(path.sep).join(path.posix.sep);
-
-      if (!existingTargetFolderSet.has(relativePath)) {
-        const targetFolderItem: ITargetFolder = {
-          folderPath: relativePath
-        };
-
-        if (lockfileId) {
-          targetFolderItem.lockfileId = lockfileId;
-        }
-
-        pnpmSyncJsonFile.postbuildInjectedCopy.targetFolders.push(targetFolderItem);
-      }
-    }
-
-    await fs.promises.writeFile(pnpmSyncJsonPath, JSON.stringify(pnpmSyncJsonFile, null, 2));
+    await pnpmSyncUpdateFileAsync({
+      sourceProjectFolder,
+      targetFolders,
+      logMessageCallback,
+      lockfileId
+    });
   }
 
   const endTime = process.hrtime.bigint();