{"id":20806302,"url":"https://github.com/nodesource/ah-fs.processor","last_synced_at":"2025-05-11T17:31:43.795Z","repository":{"id":57174679,"uuid":"80552734","full_name":"nodesource/ah-fs.processor","owner":"nodesource","description":"Processes ah-fs data obtained from async resources related to file system opearations.","archived":true,"fork":false,"pushed_at":"2017-10-26T19:09:08.000Z","size":1263,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-18T14:59:32.615Z","etag":null,"topics":["async-hooks"],"latest_commit_sha":null,"homepage":"https://nodesource.github.io/ah-fs.processor","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodesource.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-31T19:14:19.000Z","updated_at":"2025-01-30T21:17:40.000Z","dependencies_parsed_at":"2022-08-29T00:10:53.858Z","dependency_job_id":null,"html_url":"https://github.com/nodesource/ah-fs.processor","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodesource%2Fah-fs.processor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodesource%2Fah-fs.processor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodesource%2Fah-fs.processor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodesource%2Fah-fs.processor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodesource","download_url":"https://codeload.github.com/nodesource/ah-fs.processor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253604836,"owners_count":21934905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async-hooks"],"created_at":"2024-11-17T19:19:11.712Z","updated_at":"2025-05-11T17:31:43.556Z","avatar_url":"https://github.com/nodesource.png","language":"JavaScript","readme":"# ah-fs.processor [![build status](https://secure.travis-ci.org/nodesource/ah-fs.processor.png)](http://travis-ci.org/nodesource/ah-fs.processor)\n\nProcesses ah-fs data obtained from async resources related to file system opearations.\n\n## Installation\n\n    npm install ah-fs.processor\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n-   [API](#api)\n    -   [ReadFileProcessor](#readfileprocessor)\n    -   [readFileProcessor.process](#readfileprocessorprocess)\n    -   [Groups](#groups)\n    -   [Operations](#operations)\n        -   [`fs.readFile` specific Operation Properties](#fsreadfile-specific-operation-properties)\n        -   [General Operation Properties](#general-operation-properties)\n    -   [Sample Return Value](#sample-return-value)\n    -   [ReadFileProcessor.operationSteps](#readfileprocessoroperationsteps)\n    -   [ReadFileProcessor.operation.null](#readfileprocessoroperationnull)\n    -   [ReadFileOperation](#readfileoperation)\n    -   [readFileOperation.\\_processOpen](#readfileoperation%5C_processopen)\n    -   [readFileOperation.\\_processStat](#readfileoperation%5C_processstat)\n    -   [readFileOperation.\\_processRead](#readfileoperation%5C_processread)\n    -   [readFileOperation.\\_processClose](#readfileoperation%5C_processclose)\n    -   [readFileOperation.summary](#readfileoperationsummary)\n    -   [Properties Specific to `fs.readFile`](#properties-specific-to-fsreadfile)\n    -   [ReadStreamProcessor](#readstreamprocessor)\n    -   [readStreamProcessor.process](#readstreamprocessorprocess)\n    -   [Groups](#groups-1)\n    -   [Operations](#operations-1)\n        -   [`fs.createReadStream` specific Operation Properties](#fscreatereadstream-specific-operation-properties)\n        -   [General Operation Properties](#general-operation-properties-1)\n    -   [Sample Return Value](#sample-return-value-1)\n    -   [ReadStreamProcessor.operationSteps](#readstreamprocessoroperationsteps)\n    -   [ReadStreamProcessor.operation.null](#readstreamprocessoroperationnull)\n    -   [ReadStreamOperation](#readstreamoperation)\n    -   [readStreamOperation.\\_processOpen](#readstreamoperation%5C_processopen)\n    -   [readStreamOperation.\\_processTick](#readstreamoperation%5C_processtick)\n    -   [readStreamOperation.\\_processRead](#readstreamoperation%5C_processread)\n    -   [readStreamOperation.\\_processClose](#readstreamoperation%5C_processclose)\n    -   [readStreamOperation.summary](#readstreamoperationsummary)\n    -   [Properties Specific to `fs.createReadStream`](#properties-specific-to-fscreatereadstream)\n    -   [openInitFrame0Rx](#openinitframe0rx)\n    -   [writeInitFrame0Rx](#writeinitframe0rx)\n    -   [closeInitFrame0Rx](#closeinitframe0rx)\n    -   [WriteFileProcessor](#writefileprocessor)\n    -   [writeFileProcessor.process](#writefileprocessorprocess)\n    -   [Groups](#groups-2)\n    -   [Operations](#operations-2)\n        -   [`fs.createWriteFile` specific Operation Properties](#fscreatewritefile-specific-operation-properties)\n        -   [General Operation Properties](#general-operation-properties-2)\n    -   [Sample Return Value](#sample-return-value-2)\n    -   [WriteFileProcessor.operationSteps](#writefileprocessoroperationsteps)\n    -   [WriteFileProcessor.operation.null](#writefileprocessoroperationnull)\n    -   [WriteFileOperation](#writefileoperation)\n    -   [writeFileOperation.\\_processOpen](#writefileoperation%5C_processopen)\n    -   [writeFileOperation.\\_processWrite](#writefileoperation%5C_processwrite)\n    -   [writeFileOperation.\\_processClose](#writefileoperation%5C_processclose)\n    -   [writeFileOperation.summary](#writefileoperationsummary)\n    -   [Properties Specific to `fs.writeFile`](#properties-specific-to-fswritefile)\n    -   [WriteStreamProcessor](#writestreamprocessor)\n    -   [writeStreamProcessor.process](#writestreamprocessorprocess)\n    -   [Groups](#groups-3)\n    -   [Operations](#operations-3)\n        -   [`fs.createWriteStream` specific Operation Properties](#fscreatewritestream-specific-operation-properties)\n        -   [General Operation Properties](#general-operation-properties-3)\n    -   [Sample Return Value](#sample-return-value-3)\n    -   [writeStreamProcessor.\\_separteIntoGroups](#writestreamprocessor%5C_separteintogroups)\n    -   [Connecting WriteSteam Write to WriteStream Close](#connecting-writesteam-write-to-writestream-close)\n    -   [Connecting WriteStream Open to WriteStream Write](#connecting-writestream-open-to-writestream-write)\n    -   [WriteStreamProcessor.operationSteps](#writestreamprocessoroperationsteps)\n    -   [WriteStreamProcessor.operation.null](#writestreamprocessoroperationnull)\n    -   [WriteStreamOperation](#writestreamoperation)\n    -   [writeStreamOperation.\\_processOpen](#writestreamoperation%5C_processopen)\n    -   [writeStreamOperation.\\_processTick](#writestreamoperation%5C_processtick)\n    -   [writeStreamOperation.\\_processwrite](#writestreamoperation%5C_processwrite)\n    -   [writeStreamOperation.\\_processClose](#writestreamoperation%5C_processclose)\n-   [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## [API](https://nodesource.github.io/ah-fs.processor)\n\n\u003c!-- Generated by documentation.js. Update this documentation by updating the source code. --\u003e\n\n### processFileSystem\n\n**Parameters**\n\n-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** \n    -   `$0.activities` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)\u0026lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)\u003e** a map of async activities hashed by id\n    -   `$0.includeActivities` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the actual activities are appended to the output (optional, default `false`)\n\n### ReadFileProcessor\n\nInstantiates an fs.readFile data processor to process data collected via\n[nodesource/ah-fs](https://github.com/nodesource/ah-fs)\n\n**Parameters**\n\n-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** \n-   `includeActivities` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the actual activities are appended to the output (optional, default `false`)\n\n### readFileProcessor.process\n\nProcesses the supplied async activities and splits them into\ngroups, and operations each representing a file read `fs.readFile`.\n\n### Groups\n\nThe returned value has a `groups` property which just lists the ids\nof async resources that were grouped together to form an operation\nindexed by the id of the `open` resource.\nThus the `groups` is a map of sets.\nIf no file read was encountered the groups are empty.\n\n### Operations\n\nAdditionally an `operations` property is included as well. Each operation\nrepresents one full `fs.readFile` execution. There will be one operation per\ngroup and they are indexed by the corresponding open resource `id` as well.\n\nAn `operation` has the following properties:\n\n#### `fs.readFile` specific Operation Properties\n\n Data about the async resources that were part of the operation, by default\n only `id` and `triggerId` are included:\n\n-   **open**: contains data about opening the file\n-   **stat**: contains data about getting file stats\n-   **read**: contains data about reading the file\n-   **close**: contains data about closing the file\n\n#### General Operation Properties\n\nThe information below is the same for all `operation`s and thus is only\nmentioned here and linked from the documentation of all other processors.\n\n Data about the lifetime of the operation:\n\n-   **lifeCycle**: contains three timestamps that detail when an operation was created,\n    for how long it was alive and when it was destroyed.\n\n    -   **created**: the timestamp when the first resource of the operation was created\n    -   **destroyed**: the timestamp when the last resource of the operation was destroyed\n    -   **timeAlive**: the difference between the `destroyed` and `created` timestamps, i.e.\n        how long the operation's resources were alive\n\n    Each timestamp has the following two properties provided by [utils.prettyNs](#utilsprettyns).\n\n    -   **ns**: time in nanoseconds {Number}\n    -   **ms**: pretty printed time in milliseconds {String}\n\nData that links to user code that is responsible for the operation occurring.\n\n-   **createdAt**: provides the line of code that called `fs.readFile`\n-   **userFunctions**: depending on the settings (see constructor docs) each resource\n    will include it's own array of userFunctions or they are separated out into\n    one property with duplicates merged. The latter is the default behavior.\n    In either case `userFunctions` is an Array of Objects with the following properties:\n\n    -   **name**: the function name\n    -   **inferredName**: the inferred function name, only needed if the `name` is not set\n    -   **file**: the file in which the function was defined\n    -   **line**: the line on which the functino was defined in that file\n    -   **column**: the column on which the functino was defined in that file\n    -   **location**: the file and line + column where the function was defined combined into a string\n    -   **args**: the `err` and information about the `res` of the operation\n        with which the function was invoked\n    -   **propertyPaths**: the object paths at which the function was found, these could be multiple\n        since the function could've been attached to multiple resources (only available if the functions\n        were separated from the resources and merged)\n    -   **propertyPath**: the object path at which the function was found (only available if the\n        functions weren't separated and thus are still part of each resource)\n\n### Sample Return Value\n\nThe sample return value was created with default options.\n\n```js\n{ groups: Map { 10 =\u003e Set { 10, 11, 12, 13 } },\n  operations:\n    Map {\n      10 =\u003e { lifeCycle:\n        { created: { ms: '44.12ms', ns: 44119000 },\n          destroyed: { ms: '85.95ms', ns: 85955000 },\n          timeAlive: { ms: '41.84ms', ns: 41836000 } },\n      createdAt: 'at Test.\u003canonymous\u003e (/Volumes/d/dev/js/async-hooks/ah-fs/test/read-one-file.js:36:6)',\n      open: { id: 10, triggerId: 1 },\n      stat: { id: 11, triggerId: 10 },\n      read: { id: 12, triggerId: 11 },\n      close: { id: 13, triggerId: 12 },\n      userFunctions:\n        [ { file: '/Volumes/d/dev/js/async-hooks/ah-fs/test/read-one-file.js',\n            line: 39,\n            column: 17,\n            inferredName: '',\n            name: 'onread',\n            location: 'onread (/Volumes/d/dev/js/async-hooks/ah-fs/test/read-one-file.js:39:17)',\n            args:\n            { '0': null,\n              '1':\n                { type: 'Buffer',\n                  len: 6108,\n                  included: 18,\n                  val:\n                  { utf8: 'const test = requi',\n                    hex: '636f6e73742074657374203d207265717569' } },\n              proto: 'Object' },\n            propertyPaths:\n            [ 'open.resource.context.callback',\n              'stat.resource.context.callback',\n              'read.resource.context.callback',\n              'close.resource.context.callback' ] } ] } } }\n```\n\nReturns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about `fs.readFile` operations with the\nstructure outlined above\n\n### ReadFileProcessor.operationSteps\n\nThe minimum number of steps, represented as an async resource each,\ninvolved to execute `fs.readFile`.\n\nThis can be used by higher level processors to group\nactivities looking for larger operations first and then\noperations involving less steps.\n\nSteps are: open, stat, read+, close\n\n### ReadFileProcessor.operation\n\nDescription of the operation: 'fs.readFile'.\n\n### ReadFileOperation\n\nProcesses a group of async activities that represent a fs read stream operation.\nIt is used by the [ReadFileProcessor](#readfileprocessor) as part of `process`.\n\nFour operation steps are derived from the group, each providing some information\nabout the operation in question.\n\nEach step is processed into an operation in the corresponding private method, i.e. `_processOpen`.\nThese methods are documented below for information's sake, they should not be called directly,\nnor should you have a need to directly instantiate a `ReadFileOperation` in the first place.\n\n**Parameters**\n\n-   `group` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)\u0026lt;[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)\u0026lt;[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)\u003e\u003e** the ids of the activities that were part of the operation\n-   `includeActivities` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the activities are attached to\n    each operation step (optional, default `false`)\n\n### readFileOperation.\\_processOpen\n\nThe open resource tells us where in user code the `fs.readFile` originated\nvia the second frame of the stack trace, as well as when the operation\nwas created.\n\nAdditionally it has the same user functions attached as all the other resources.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the open step, pre-processed by the `ReadFileProcessor`.\n\n### readFileOperation.\\_processStat\n\nThe stat resource gives us no interesting information.\nTherefore we just capture the `id`, `triggerId` and `userFunctions` and if so desired\nattach the activities.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the open step, pre-processed by the `ReadFileProcessor`.\n\n### readFileOperation.\\_processRead\n\nThe read resource gives us no interesting information.\nTherefore we just capture the `id`, `triggerId` and `userFunctions` and if so desired\nattach the activities.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the read step, pre-processed by the `ReadFileProcessor`.\n\n### readFileOperation.\\_processClose\n\nThe main information we pull from the close resource is the `destroy` timestamp.\n\nCombined with the `init` timestamp of the open resource it allows us to deduce how long\nthe file read took.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the close step, pre-processed by the `ReadFileProcessor`.\n\n### readFileOperation.summary\n\nReturns the summary of processing the group into an operation.\n\nThe summary of all operations has a very similar structure, but includes some properties that are specific to this\nparticular operation.\n\nThe general properties `lifeCycle` and `createdAt` are documented as part of\nthe `ReadFileProcessor`.\nTherefore learn more [here](#general-operation-properties).\n\n### Properties Specific to `fs.readFile`\n\n-   **open**: see `readFileOperation._processOpen`\n-   **stat**: see `readFileOperation._processStat`\n-   **read**: see `readFileOperation._processRead`\n-   **close**: see `readFileOperation._processClose`\n\n**Parameters**\n\n-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options\n    -   `$0.separateFunctions` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** when `true` the user functions are separated out\n        from the specific operations and attached as a `userFunctions` array directly to the returned\n        result (optional, default `true`)\n    -   `$0.mergeFunctions` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` when a duplicate function is found in the\n        separated functions Array, they are merged into one while preserving all information\n        from both version. Note that this setting only activates if `separateFunctions` is `true` as well. (optional, default `true`)\n\nReturns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** all important information about the current operation\n\n### ReadStreamProcessor\n\nInstantiates an fs.createReadStream data processor to process data collected via\n[nodesource/ah-fs](https://github.com/nodesource/ah-fs)\n\n**Parameters**\n\n-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** \n-   `includeActivities` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the actual activities are appended to the output (optional, default `false`)\n\n### readStreamProcessor.process\n\nProcesses the supplied async activities and splits them into\ngroups, and operations each representing a file read stream `fs.createReadStream`.\n\n### Groups\n\nThe returned value has a `groups` property which just lists the ids\nof async resources that were grouped together to form an operation\nindexed by the `fd` on which the readFile operated.\nThus the `groups` is a map of sets.\nIf no file read stream was encountered the groups are empty.\n\n### Operations\n\nAdditionally an `operations` property is included as well. Each operation\nrepresents one full `fs.createReadStream` execution. There will be one operation per\ngroup and they are indexed by the corresponding `fd` as well.\n\nAn `operation` has the following properties:\n\n#### `fs.createReadStream` specific Operation Properties\n\n Data about the async resources that were part of the operation, by default\n only `id` and `triggerId` are included:\n\n-   **open**: contains data about opening the file\n-   **stream**: contains data about how the stream was configured, including readable state and\n    the path to the file being read, pipes count, encoding, etc.\n-   **reads**: an Array of reads, each containing data about reading a chunk from the file including\n    the time spent to complete reading the particular chunk\n-   **close**: contains data about closing the file\n\n#### General Operation Properties\n\n-   [see ReadFileProcessor.process](https://nodesource.github.io/ah-fs.processor/#general-operation-properties)\n\n### Sample Return Value\n\nThe sample return value was created with default options.\n\n```js\n{ groups: Map { 10 =\u003e Set { 10, 12, 13, 14, 16 } },\n  operations:\n  Map {\n    10 =\u003e { lifeCycle:\n      { created: { ms: '1.60ms', ns: 1600000 },\n        destroyed: { ms: '14.33ms', ns: 14329000 },\n        timeAlive: { ms: '12.73ms', ns: 12729000 } },\n    createdAt: 'at Test.\u003canonymous\u003e (/Volumes/d/dev/js/async-hooks/ah-fs/test/readstream-one-file.js:94:6)',\n    open: { id: 10, triggerId: 3 },\n    stream:\n      { id: 14,\n        triggerId: 12,\n        path: '/Volumes/d/dev/js/async-hooks/ah-fs/test/readstream-one-file.js',\n        flags: 'r',\n        fd: 19,\n        objectMode: false,\n        highWaterMark: 65536,\n        pipesCount: 0,\n        defaultEncoding: 'utf8',\n        encoding: null },\n    reads:\n      [ { id: 12,\n          triggerId: 10,\n          timeSpent: { ms: '0.83ms', ns: 830000 } },\n        { id: 13,\n          triggerId: 12,\n          timeSpent: { ms: '0.24ms', ns: 240000 } } ],\n    close: { id: 16, triggerId: 13 },\n    userFunctions:\n      [ { file: '/Volumes/d/dev/js/async-hooks/ah-fs/test/readstream-one-file.js',\n          line: 99,\n          column: 16,\n          inferredName: '',\n          name: 'onend',\n          location: 'onend (/Volumes/d/dev/js/async-hooks/ah-fs/test/readstream-one-file.js:99:16)',\n          args: null,\n          propertyPaths: [ 'stream.resource.args[0]._events.end[1]' ] },\n        { file: '/Volumes/d/dev/js/async-hooks/ah-fs/test/readstream-one-file.js',\n          line: 98,\n          column: 17,\n          inferredName: '',\n          name: 'ondata',\n          location: 'ondata (/Volumes/d/dev/js/async-hooks/ah-fs/test/readstream-one-file.js:98:17)',\n          args: null,\n          propertyPaths: [ 'stream.resource.args[0]._events.data' ] } ] } } }\n```\n\nReturns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about `fs.createReadStream` operations with the\nstructure outlined above\n\n### ReadStreamProcessor.operationSteps\n\nThe minimum number of steps, represented as an async resource each,\ninvolved to execute `fs.createReadStream`.\n\nThis can be used by higher level processors to group\nactivities looking for larger operations first and then\noperations involving less steps.\n\nSteps are: open, stream+, read+, close\n\n### ReadStreamProcessor.operation.null\n\nDescription of the operation: 'fs.createReadStream'.\n\n### ReadStreamOperation\n\nProcesses a group of async activities that represent a fs read stream operation.\nIt is used by the [ReadStreamProcessor](#readstreamprocessor) as part of `process`.\n\nFour operation steps are derived from the group, each providing some information\nabout the operation in question.\n\nEach step is processed into an operation in the corresponding private method, i.e. `_processOpen`.\nThese methods are documented below for information's sake, they should not be called directly,\nnor should you have a need to directly instantiate a `ReadStreamOperation` in the first place.\n\n**Parameters**\n\n-   `group` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)\u0026lt;[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)\u0026lt;[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)\u003e\u003e** the ids of the activities that were part of the operation\n-   `includeActivities` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the activities are attached to\n    each operation step (optional, default `false`)\n\n### readStreamOperation.\\_processOpen\n\nAn open doesn't have too much info, but we can glean two very important\n data points:\n\n1.  the init timestamp tells us when the stream was created\n2.  the last frame of the init stack tells us where `createReadStream` was called.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the open step, pre-processed by the `ReadStreamProcessor`.\n\n### readStreamOperation.\\_processTick\n\nThe ReadStream Tick gives us a lot of information. It has an args array with\nthe ReadStream and its ReadableState respectively\n\nThe ReadStream provides us the following:\n\n1.  the path to the file we are streaming\n2.  the flags with which the file was opened\n3.  the fd (assuming we are dealing with the tick triggered indirectly by the open)\n\nAll callbacks on the \\_events of the ReadStream have been removed, but are present\ninside the functions object (see below).\n\nThe ReadableState provides us the following:\n\n1.  objectMode `true|false`\n2.  highWaterMark\n3.  pipesCount\n4.  defaultEncoding, i.e. utf8\n5.  encoding, i.e. utf8\n\nThe information extracted from the tick is attached to a `stream` property\nprovided with the `summary`.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the tick step, pre-processed by the `ReadStreamProcessor`.\n\n### readStreamOperation.\\_processRead\n\nThe read resource doesn't give us too much information.\n\nThe stack traces originate in core and we don't see any registred\nuser callbacks, as those are present on the stream instead.\nHowever we can count the amount of reads that occurred and deduce how\nlong each read took from the `before` and `after` timestamps.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the read step, pre-processed by the `ReadStreamProcessor`.\n\n### readStreamOperation.\\_processClose\n\nThe main information we pull from the close resource is the `destroy` timestamp.\n\nCombined with the `init` timestamp of the open resource it allows us to deduce how long\nthe read stream was active.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the close step, pre-processed by the `ReadStreamProcessor`.\n\n### readStreamOperation.summary\n\nReturns the summary of processing the group into an operation.\n\nThe summary of all operations has a very similar structure, but includes some properties that are specific to this\nparticular operation.\n\nThe general properties `lifeCycle` and `createdAt` are documented as part of\nthe `ReadFileProcessor`.\nTherefore learn more [here](#general-operation-properties).\n\n### Properties Specific to `fs.createReadStream`\n\n-   **open**: see `readStreamOperation._processOpen`\n-   **stream**: see `readStreamOperation._processTick`\n-   **read**: see `readStreamOperation._processRead`\n-   **close**: see `readStreamOperation._processClose`\n\n**Parameters**\n\n-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options\n    -   `$0.separateFunctions` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** when `true` the user functions are separated out\n        from the specific operations and attached as a `userFunctions` array directly to the returned\n        result (optional, default `true`)\n    -   `$0.mergeFunctions` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` when a duplicate function is found in the\n        separated functions Array, they are merged into one while preserving all information\n        from both version. Note that this setting only activates if `separateFunctions` is `true` as well. (optional, default `true`)\n\nReturns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** all important information about the current operation\n\n### openInitFrame0Rx\n\nSample initStack of writeFile open, calles as first operation of `fs.writeFile`.\nIn order to be sure this is a writeFile open we need to check the two topmost frames.\n\n\"at Object.fs.open (fs.js:581:11)\",\n\"at Object.fs.writeFile (fs.js:1155:6)\",\n\"at Test.\u003canonymous\u003e (/Volumes/d/dev/js/async-hooks/ah-fs/test/write-one-file.js:28:6)\",\n\nCode at fs.js:581:\n\n`binding.open(pathModule._makeLong(path), ...`\n\nCode at fs.js:1155:\n\n`fs.open(path, flag, options.mode, function(openErr, fd) ...`\n\nBottom frame has info about where the call `fs.writeFile` originated.\n\n### writeInitFrame0Rx\n\nSample init stack of writeFile write, called afer `fs.open` completes:\n\n\"at Object.fs.write (fs.js:643:20)\",\n\"at writeAll (fs.js:1117:6)\",\n\"at writeFd (fs.js:1168:5)\",\n\"at fs.js:1159:7\",\n\"at FSReqWrap.oncomplete (fs.js:117:15)\"\n\nCode at fs.js:643:\n\n`binding.writeBuffer(fd, buffer, offset, length, position, req);`\n\n### closeInitFrame0Rx\n\nSample initStack of writeFile close, called after last `fs.write` completes:\n\n\"at Object.fs.close (fs.js:555:11)\",\n\"at fs.js:1131:14\",\n\"at FSReqWrap.wrapper [as oncomplete](fs.js:626:5)\"\n\nCode at fs.js:555:\n\n`binding.close(fd, req);`\n\n### WriteFileProcessor\n\nInstantiates an fs.writeFile data processor to process data collected via\n[nodesource/ah-fs](https://github.com/nodesource/ah-fs)\n\n**Parameters**\n\n-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** \n-   `includeActivities` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the actual activities are appended to the output (optional, default `false`)\n\n### writeFileProcessor.process\n\nProcesses the supplied async activities and splits them into\ngroups, and operations each representing a file read stream `fs.createWriteFile`.\n\n### Groups\n\nThe returned value has a `groups` property which just lists the ids\nof async resources that were grouped together to form an operation\nindexed by the id of the `fs.open` activity that was part of the `fs.writeFile`.\nThus the `groups` is a map of sets.\nIf no file write file was encountered the groups are empty.\n\n### Operations\n\nAdditionally an `operations` property is included as well. Each operation\nrepresents one full `fs.writeFile` execution. There will be one operation per\ngroup and they are indexed by the corresponding open id as well.\n\nAn `operation` has the following properties:\n\n#### `fs.createWriteFile` specific Operation Properties\n\n Data about the async resources that were part of the operation, by default\n only `id` and `triggerId` are included:\n\n-   **open**: contains data about opening the file\n-   **writes**: an Array of writes, each containing data about writing a\n    chunk from the file including the time spent to complete writing the\n    particular chunk\n-   **close**: contains data about closing the file\n\n#### General Operation Properties\n\n-   [see ReadFileProcessor.process](https://nodesource.github.io/ah-fs.processor/#general-operation-properties)\n\n### Sample Return Value\n\nThe sample return value was created with default options.\n\n```js\n{ groups: Map { 10 =\u003e Set { 10, 11, 12 } },\n  operations:\n  Map {\n    10 =\u003e { lifeCycle:\n      { created: { ms: '24.49ms', ns: 24491000 },\n        destroyed: { ms: '33.96ms', ns: 33964000 },\n        timeAlive: { ms: '9.47ms', ns: 9473000 } },\n    createdAt: 'at Test.\u003canonymous\u003e (/Volumes/d/dev/js/async-hooks/ah-fs/test/write-one-file.js:28:6)',\n    open: { id: 10, triggerId: 1 },\n    write: { id: 11, triggerId: 10 },\n    close: { id: 12, triggerId: 11 } } } }\n```\n\nReturns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about `fs.createWriteFile` operations with the\nstructure outlined above\n\n### WriteFileProcessor.operationSteps\n\nThe minimum number of steps, represented as an async resource each,\ninvolved to execute `fs.writeFile`.\n\nThis can be used by higher level processors to group\nactivities looking for larger operations first and then\noperations involving less steps.\n\nSteps are: open, write+, close\n\n### WriteFileProcessor.operation.null\n\nDescription of the operation: 'fs.writeFile'.\n\n### WriteFileOperation\n\nProcesses a group of async activities that represent a fs write file operation.\nIt is used by the [WriteFileProcessor](#WriteFileProcessor) as part of `process`.\n\nThree operation steps are derived from the group, each providing some information\nabout the operation in question.\n\nEach step is processed into an operation in the corresponding private method, i.e. `_processOpen`.\nThese methods are documented below for information's sake, they should not be called directly,\nnor should you have a need to directly instantiate a `WriteFileOperation` in the first place.\n\n**Parameters**\n\n-   `group` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)\u0026lt;[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)\u0026lt;[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)\u003e\u003e** the ids of the activities that were part of the operation\n-   `includeActivities` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the activities are attached to\n    each operation step (optional, default `false`)\n\n### writeFileOperation.\\_processOpen\n\nThe open resource tells us where in user code the `fs.writeFile` originated\nvia the second frame of the stack trace, as well as when the operation\nwas created.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the open step, pre-processed by the `WriteFileProcessor`.\n\n### writeFileOperation.\\_processWrite\n\nThe write resource gives us no interesting information.\nTherefore we just capture the `id`, `triggerId` and if so desired\nattach the activities.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the write step, pre-processed by the `WriteFileProcessor`.\n\n### writeFileOperation.\\_processClose\n\nThe main information we pull from the close resource is the `destroy` timestamp.\n\nCombined with the `init` timestamp of the open resource it allows us to deduce how long\nthe file write took.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the close step, pre-processed by the `WriteFileProcessor`.\n\n### writeFileOperation.summary\n\nReturns the summary of processing the group into an operation.\n\nThe summary of all operations has a very similar structure, but includes some properties that are specific to this\nparticular operation.\n\nThe general properties `lifeCycle` and `createdAt` are documented as part of\nthe `WriteFileProcessor`.\nTherefore learn more [here](#general-operation-properties).\n\n### Properties Specific to `fs.writeFile`\n\n-   **open**: see `writeFileOperation._processOpen`\n-   **write**: see `writeFileOperation._processWrite`\n-   **close**: see `writeFileOperation._processClose`\n\nNote this summary function takes no parameters (like the other Operations) since\nwe don't find any user functions related to the write file operation and thus\nhave nothing to process.\n\nReturns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** all important information about the current operation\n\n### WriteStreamProcessor\n\nInstantiates an fs.createWriteStream data processor to process data collected via\n[nodesource/ah-fs](https://github.com/nodesource/ah-fs)\n\n**Parameters**\n\n-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** \n    -   `$0.includeActivities` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the actual activities are appended to the output (optional, default `false`)\n    -   `$0.separateFunctions` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** when `true` the user functions are separated out\n        from the specific resources and attached as a `userFunctions` array directly to the returned\n        operations (optional, default `true`)\n\n### writeStreamProcessor.process\n\nProcesses the supplied async activities and splits them into\ngroups, and operations each representing a file write stream `fs.createWriteStream`.\n\n### Groups\n\nThe returned value has a `groups` property which just lists the ids\nof async resources that were grouped together to form an operation\nindexed by the `fd` on which the writeFile operated.\nThus the `groups` is a map of sets.\nIf no file write stream was encountered the groups are empty.\n\n### Operations\n\nAdditionally an `operations` property is included as well. Each operation\nrepresents one full `fs.createWriteStream` execution. There will be one operation per\ngroup and they are indexed by the corresponding `fd` as well.\n\nAn `operation` has the following properties:\n\n#### `fs.createWriteStream` specific Operation Properties\n\n Data about the async resources that were part of the operation, by default\n only `id` and `triggerId` are included:\n\n-   **open**: contains data about opening the file\n-   **stream**: contains data about how the stream was configured, including writeable state and\n    the path to the file being write, pipes count, encoding, etc.\n-   **writes**: an Array of writes, each containing data about writing a chunk from the file including\n    the time spent to complete writeing the particular chunk\n-   **close**: contains data about closing the file\n\n#### General Operation Properties\n\n-   [see ReadFileProcessor.process](https://nodesource.github.io/ah-fs.processor/#general-operation-properties)\n\n### Sample Return Value\n\nThe sample return value was created with default options.\n\n```js\n{ groups: Map { 10 =\u003e Set { 14, 10, 16, 19 } },\n  operations:\n  Map {\n    10 =\u003e { lifeCycle:\n      { created: { ms: '1.12ms', ns: 1123000 },\n        destroyed: { ms: '18.20ms', ns: 18205000 },\n        timeAlive: { ms: '17.08ms', ns: 17082000 } },\n    createdAt: 'at Test.\u003canonymous\u003e (/Volumes/d/dev/js/async-hooks/ah-fs/test/read-stream-piped-into-write-stream.js:29:26)',\n    open: { id: 10, triggerId: 3 },\n    stream:\n      { id: 16,\n        triggerId: 13,\n        path: '/dev/null',\n        flags: 'w',\n        fd: 19,\n        mode: 438 },\n    writes:\n      [ { id: 14,\n          triggerId: 13,\n          timeSpent: { ms: '0.14ms', ns: 139000 } } ],\n    close: { id: 19, triggerId: 15 },\n    userFunctions:\n      [ { file: '/Volumes/d/dev/js/async-hooks/ah-fs/test/read-stream-piped-into-write-stream.js',\n          line: 32,\n          column: 19,\n          inferredName: '',\n          name: 'onfinish',\n          location: 'onfinish (/Volumes/d/dev/js/async-hooks/ah-fs/test/read-stream-piped-into-write-stream.js:32:19)',\n          args: null,\n          propertyPaths: [ 'stream.resource.args[1].pipes._events.finish[1]' ] } ] } } }\n```\n\nReturns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about `fs.createWriteStream` operations with the\nstructure outlined above\n\n### writeStreamProcessor.\\_separteIntoGroups\n\nHere we try our best to piece together the parts of a WriteStream,\nOpen | Write+ | WriteStreamTick | Close.\n\nSince they aren't linked by a common file descriptor or similar we rely\non async resource graph structure and the timestamps to take a best guess.\n\nWe just don't have the data available to piece this together with 100% certainty.\n\nBelow is a sample of collected async resources with all but types and ids removed.\n\n     { type: 'FSREQWRAP', id: 10, tid: 3 }   open, write stream triggered by root\n     { type: 'FSREQWRAP', id: 11, tid: 3 }   open, read stream triggered by root\n     { type: 'TickObject', id: 12, tid: 3 }  read stream tick, triggered by root\n     { type: 'FSREQWRAP', id: 13, tid: 11 }  read, triggerd by open of read steam\n     { type: 'FSREQWRAP', id: 14, tid: 13 }  write, triggerd by read of read steam\n     { type: 'FSREQWRAP', id: 15, tid: 13 }  read, next chunk, triggered by first read\n     { type: 'TickObject', id: 16, tid: 13 } stream tick, triggerd by first read\n     { type: 'FSREQWRAP', id: 18, tid: 15 }  close read stream, triggered by last read\n     { type: 'FSREQWRAP', id: 19, tid: 15 }  close write stream, triggered by last read\n\nWe reason about that data as follows in order to piece together the WriteStream.\n\n### Connecting WriteSteam Write to WriteStream Close\n\nWrite (id: 14) is triggered by read of read stream (id: 13).\nThe same read triggers the last read (id: 15).\nThat last read triggers the close of the write stream (id: 19).\n\nTherefore we can connect the write stream write to the write stream close since they\nhave a common parent in their ancestry (the first read of the read stream).\n\n               -- Read2:15 -- WriteStream:Close:19\n             /\n    Read1:13\n             \\\n               -- WriteStream:Write:14\n\nHowever I would imagine that this breaks down once we have on read stream piped into multiple\nwrite streams as then the writes have the same Read parent.\n\n### Connecting WriteStream Open to WriteStream Write\n\nThere is no 100% way to get this right, but if we assume that the first write happens right after\nthe opening of the write stream in the same context we can do the following.\n\nWe already know that the common parent of WriteStream:Write and\nWriteStream:Close is Read1:13.\nTherefore we find all WriteStream:Opens that share a parent with Read1:13.\nThe ones with the closest parent win.\n\nIf we find more than one, we pick the one that was initialized closest to\nthe WriteStream:Write timewise, assuming that we write to the stream\nimmediately after opening it.\n\n               -- ReadStream:Open:11 -- Read1:13 -- Read2:15 -- WriteStream:Close:19\n             /                                   \\\n    Parent:3                                       -- WriteStream:Write:14\n             \\\n               -- WriteStream:Open:10\n\n### WriteStreamProcessor.operationSteps\n\nThe minimum number of steps, represented as an async resource each,\ninvolved to execute `fs.createWriteStream`.\n\nThis can be used by higher level processors to group\nactivities looking for larger operations first and then\noperations involving less steps.\n\nSteps are: open, stream, write+, close\n\n### WriteStreamProcessor.operation.null\n\nDescription of the operation: 'fs.createWriteStream'.\n\n### WriteStreamOperation\n\nProcesses a group of async activities that represent a fs write stream operation.\nIt is used by the [writeStreamProcessor](#writestreamprocessor) as part of `process`.\n\nFour operation steps are derived from the group, each providing some information\nabout the operation in question.\n\nEach step is processed into an operation in the corresponding private method, i.e. `_processOpen`.\nThese methods are documented below for information's sake, they should not be called directly,\nnor should you have a need to directly instantiate a `writeStreamOperation` in the first place.\n\n**Parameters**\n\n-   `group` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)\u0026lt;[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)\u0026lt;[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)\u003e\u003e** the ids of the activities that were part of the operation\n-   `includeActivities` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** if `true` the activities are attached to\n    each operation step (optional, default `false`)\n\n### writeStreamOperation.\\_processOpen\n\nAn open doesn't have too much info, but we can glean two very important\n data points:\n\n1.  the init timestamp tells us when the stream was created\n2.  the last frame of the init stack tells us where `createWriteStream` was called.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the open step, pre-processed by the `WriteStreamProcessor`.\n\n### writeStreamOperation.\\_processTick\n\nThe WriteStream Tick gives us a lot of information. It is the same tick object that we process\nin the ReadStreamOperation to glean data about the read stream.\nIt has an args array with the ReadStream and its ReadableState respectively.\n\nThe ReadableState included the WritableState which the [ah-fs](https://github.com/nodesource/ah-fs) pre-processor\nalready plucked for us and added as the 3rd argument.\nAdditionally it includes lots of functions including user functions registered with the\nWriteStream, i.e. `on('finish')`.\n\nErgo the WriteStream provides us the following as part of the WritableState:\n\n1.  the path to the file we are writing into\n2.  the flags with which the file was opened\n3.  the fd (assuming we are dealing with the tick triggered indirectly by the open)\n\nAll callbacks on the \\_events of the ReadStream and WriteStream have been removed, but are present\ninside the functions object (see below).\n\nThe information extracted from the tick is attached to a `stream` property\nprovided with the `summary`.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the tick step, pre-processed by the `WriteStreamProcessor`.\n\n### writeStreamOperation.\\_processwrite\n\nThe write resource doesn't give us too much information.\n\nThe stack traces originate in core and we don't see any registred\nuser callbacks, as those are present on the stream instead.\nHowever we can count the amount of writes that occurred and deduce how\nlong each write took from the `before` and `after` timestamps.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the write step, pre-processed by the `WriteStreamProcessor`.\n\n### writeStreamOperation.\\_processClose\n\nThe main information we pull from the close resource is the `destroy` timestamp.\n\nCombined with the `init` timestamp of the open resource it allows us to deduce how long\nthe write stream was active.\n\n**Parameters**\n\n-   `info` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** information about the close step, pre-processed by the `WriteStreamProcessor`.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodesource%2Fah-fs.processor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodesource%2Fah-fs.processor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodesource%2Fah-fs.processor/lists"}