msfs-layout-generator 0.3.2 → 0.3.3

package/README.MD

@@ -55,13 +55,77 @@ Use your manager (npm, yarn, bun etc.) to install the package:
 ```bash  
 npm install msfs-layout-generator
 ```      
-Import the generator in your TypeScript / JavaScript projects:
+
+### Simple Usage
+
 ```ts  
 import { generateLayout } from 'msfs-layout-generator';  
   
-// Process a single package  
+// Process a single package (throws on errors, uses default options)
 await generateLayout("F:\\fs20\\Community\\my-package");  
 ```  
+
+### Advanced Usage with Options
+
+```ts
+import { processLayout } from 'msfs-layout-generator';
+import type { ProcessOptions, ProcessResult } from 'msfs-layout-generator';
+
+// Overwrite existing layout.json silently
+await processLayout("./my-package", { force: true, quiet: true });
+
+// Get a result object instead of throwing on errors
+const result = await processLayout("./my-package", {
+  returnResult: true,
+  force: true
+});
+
+if (result.success) {
+  console.log(`Processed ${result.fileCount} files (${result.totalSize} bytes)`);
+} else {
+  console.error(result.message);
+}
+
+// Generate layout without requiring or updating manifest.json
+await processLayout("./my-package", {
+  force: true,
+  checkManifest: false,
+  skipManifestUpdate: true
+});
+```
+
+### Exports
+
+| Export | Type | Description |
+|---|---|---|
+| `generateLayout(dir)` | `(dir: string) => Promise<void>` | Simple wrapper — processes a package directory with default options. Throws on errors. |
+| `processLayout(dir, options?)` | `(dir: string, options?: ProcessOptions) => Promise<void \| ProcessResult>` | Full-featured function with configurable options. |
+
+### `ProcessOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `force` | `boolean` | `false` | Overwrite existing `layout.json` |
+| `quiet` | `boolean` | `false` | Suppress all console output |
+| `debug` | `boolean` | `false` | Enable verbose debug logging |
+| `checkManifest` | `boolean` | `true` | Require `manifest.json` to exist in the package directory |
+| `skipManifestUpdate` | `boolean` | `false` | Skip updating `total_package_size` in `manifest.json` |
+| `returnResult` | `boolean` | `false` | Return a `ProcessResult` object instead of `void`. When `true`, errors are returned in the result instead of thrown. |
+
+### `ProcessResult`
+
+Returned when `returnResult` is `true`:
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | `boolean` | Whether the operation completed successfully |
+| `fileCount` | `number` | Number of files included in `layout.json` |
+| `totalSize` | `number` | Total package size in bytes |
+| `layoutPath` | `string` | Absolute path to the generated `layout.json` |
+| `manifestPath` | `string` | Absolute path to `manifest.json` |
+| `skippedFiles` | `number` | Number of files that were excluded |
+| `message` | `string?` | Error message (when `success` is `false`) |
+
 ---  
 
 **Happy Flying! ✈️** 

package/dist/index.d.ts

@@ -1,8 +1,9 @@
+import { processLayout } from "./utils/processLayout";
 /**
- * Process an MSFS package directory to generate/update layout.json
+ * Process an MSFS package directory to generate/update layout.json (simple API).
  *
- * This function scans all files in the package directory, creates a layout.json
- * with file metadata, and updates the total_package_size in manifest.json.
+ * This is a convenience wrapper around {@link processLayout} that uses default
+ * options and throws on errors. For more control, use {@link processLayout} directly.
  *
  * @param packageDir - Path to the MSFS package directory (must contain manifest.json)
  * @returns Promise that resolves when layout.json has been generated
@@ -12,7 +13,7 @@
  *
  * @example
  * // Basic usage
- * await doProcessLayoutFile("F:\\fs20\\Community\\my-package");
+ * await generateLayout("F:\\fs20\\Community\\my-package");
  *
  * @example
  * // With error handling
@@ -24,4 +25,5 @@
  * }
  */
 export declare const generateLayout: (layoutPath: string) => Promise<void>;
+export { processLayout };
 export type { Content, Layout, Manifest, ProcessOptions, ProcessResult } from "./types";

package/dist/index.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateLayout = void 0;
+exports.processLayout = exports.generateLayout = void 0;
 const processLayout_1 = require("./utils/processLayout");
+Object.defineProperty(exports, "processLayout", { enumerable: true, get: function () { return processLayout_1.processLayout; } });
 /**
- * Process an MSFS package directory to generate/update layout.json
+ * Process an MSFS package directory to generate/update layout.json (simple API).
  *
- * This function scans all files in the package directory, creates a layout.json
- * with file metadata, and updates the total_package_size in manifest.json.
+ * This is a convenience wrapper around {@link processLayout} that uses default
+ * options and throws on errors. For more control, use {@link processLayout} directly.
  *
  * @param packageDir - Path to the MSFS package directory (must contain manifest.json)
  * @returns Promise that resolves when layout.json has been generated
@@ -16,7 +17,7 @@ const processLayout_1 = require("./utils/processLayout");
  *
  * @example
  * // Basic usage
- * await doProcessLayoutFile("F:\\fs20\\Community\\my-package");
+ * await generateLayout("F:\\fs20\\Community\\my-package");
  *
  * @example
  * // With error handling

package/dist/utils/processLayout.d.ts

@@ -1,11 +1,45 @@
 import { ProcessOptions, ProcessResult } from "../types";
 /**
- * Unified function to process layout files for MSFS packages
- * Can be used both programmatically and via CLI
+ * Process layout files for MSFS packages with full control over behavior.
  *
- * @param packageDir - Path to MSFS package directory
- * @param options - Processing options
- * @returns Promise<void> if returnResult=false, Promise<ProcessResult> if returnResult=true
+ * Scans all files in the package directory, generates a `layout.json` with
+ * file metadata (path, size, date), and optionally updates `total_package_size`
+ * in `manifest.json`.
+ *
+ * @param packageDir - Absolute or relative path to the MSFS package directory
+ * @param options - Processing options to control behavior
+ * @param options.force - Overwrite existing layout.json (default: `false`)
+ * @param options.quiet - Suppress all console output (default: `false`)
+ * @param options.debug - Enable verbose debug logging (default: `false`)
+ * @param options.checkManifest - Require manifest.json to exist (default: `true`)
+ * @param options.skipManifestUpdate - Skip updating total_package_size in manifest.json (default: `false`)
+ * @param options.returnResult - Return a {@link ProcessResult} object instead of throwing on errors (default: `false`)
+ * @returns `Promise<void>` when `returnResult` is `false`; `Promise<ProcessResult>` when `returnResult` is `true`
+ *
+ * @throws {Error} If directory doesn't exist (when `returnResult` is `false`)
+ * @throws {Error} If manifest.json is missing and `checkManifest` is `true` (when `returnResult` is `false`)
+ * @throws {Error} If no valid files are found (when `returnResult` is `false`)
+ *
+ * @example
+ * // Overwrite existing layout.json silently
+ * await processLayout("./my-package", { force: true, quiet: true });
+ *
+ * @example
+ * // Get a result object instead of throwing
+ * const result = await processLayout("./my-package", { returnResult: true, force: true });
+ * if (result.success) {
+ *   console.log(`Processed ${result.fileCount} files (${result.totalSize} bytes)`);
+ * } else {
+ *   console.error(result.message);
+ * }
+ *
+ * @example
+ * // Generate layout without requiring or updating manifest.json
+ * await processLayout("./my-package", {
+ *   force: true,
+ *   checkManifest: false,
+ *   skipManifestUpdate: true
+ * });
  */
 export declare const processLayout: (packageDir: string, options?: ProcessOptions) => Promise<void | ProcessResult>;
 export declare const doProcessLayoutFile: (layoutPath: string) => Promise<void>;

package/dist/utils/processLayout.js

@@ -41,12 +41,46 @@ const promises_1 = require("fs/promises");
 const getWindowsFileTime_1 = require("./getWindowsFileTime");
 const doUpdateManifest_1 = require("./doUpdateManifest");
 /**
- * Unified function to process layout files for MSFS packages
- * Can be used both programmatically and via CLI
+ * Process layout files for MSFS packages with full control over behavior.
  *
- * @param packageDir - Path to MSFS package directory
- * @param options - Processing options
- * @returns Promise<void> if returnResult=false, Promise<ProcessResult> if returnResult=true
+ * Scans all files in the package directory, generates a `layout.json` with
+ * file metadata (path, size, date), and optionally updates `total_package_size`
+ * in `manifest.json`.
+ *
+ * @param packageDir - Absolute or relative path to the MSFS package directory
+ * @param options - Processing options to control behavior
+ * @param options.force - Overwrite existing layout.json (default: `false`)
+ * @param options.quiet - Suppress all console output (default: `false`)
+ * @param options.debug - Enable verbose debug logging (default: `false`)
+ * @param options.checkManifest - Require manifest.json to exist (default: `true`)
+ * @param options.skipManifestUpdate - Skip updating total_package_size in manifest.json (default: `false`)
+ * @param options.returnResult - Return a {@link ProcessResult} object instead of throwing on errors (default: `false`)
+ * @returns `Promise<void>` when `returnResult` is `false`; `Promise<ProcessResult>` when `returnResult` is `true`
+ *
+ * @throws {Error} If directory doesn't exist (when `returnResult` is `false`)
+ * @throws {Error} If manifest.json is missing and `checkManifest` is `true` (when `returnResult` is `false`)
+ * @throws {Error} If no valid files are found (when `returnResult` is `false`)
+ *
+ * @example
+ * // Overwrite existing layout.json silently
+ * await processLayout("./my-package", { force: true, quiet: true });
+ *
+ * @example
+ * // Get a result object instead of throwing
+ * const result = await processLayout("./my-package", { returnResult: true, force: true });
+ * if (result.success) {
+ *   console.log(`Processed ${result.fileCount} files (${result.totalSize} bytes)`);
+ * } else {
+ *   console.error(result.message);
+ * }
+ *
+ * @example
+ * // Generate layout without requiring or updating manifest.json
+ * await processLayout("./my-package", {
+ *   force: true,
+ *   checkManifest: false,
+ *   skipManifestUpdate: true
+ * });
  */
 const processLayout = async (packageDir, options = {}) => {
     const { force = false, quiet = false, debug = false, checkManifest = true, skipManifestUpdate = false, returnResult = false // Default: behave like old doProcessLayoutFile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msfs-layout-generator",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Generate layout.json for MSFS community packages",
   "repository": {
     "type": "git",