{"id":15598208,"url":"https://github.com/boneskull/snapshot-fs","last_synced_at":"2025-10-12T09:39:35.238Z","repository":{"id":226689709,"uuid":"767259355","full_name":"boneskull/snapshot-fs","owner":"boneskull","description":"Create a snapshot of a directory for use with memfs","archived":false,"fork":false,"pushed_at":"2025-10-10T16:48:48.000Z","size":1399,"stargazers_count":4,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-10T18:02:57.324Z","etag":null,"topics":["filesystem","fixture","json","memfs","snapshot","testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boneskull.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["boneskull"]}},"created_at":"2024-03-05T01:06:55.000Z","updated_at":"2025-10-10T16:48:02.000Z","dependencies_parsed_at":"2024-03-09T02:31:53.336Z","dependency_job_id":"b7a1217c-f0ae-4a2d-9aa1-e36bb1b807d8","html_url":"https://github.com/boneskull/snapshot-fs","commit_stats":null,"previous_names":["boneskull/snapshot-fs"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/boneskull/snapshot-fs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fsnapshot-fs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fsnapshot-fs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fsnapshot-fs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fsnapshot-fs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boneskull","download_url":"https://codeload.github.com/boneskull/snapshot-fs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fsnapshot-fs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010796,"owners_count":26084807,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["filesystem","fixture","json","memfs","snapshot","testing"],"created_at":"2024-10-03T01:30:40.440Z","updated_at":"2025-10-12T09:39:35.195Z","avatar_url":"https://github.com/boneskull.png","language":"TypeScript","funding_links":["https://github.com/sponsors/boneskull"],"categories":[],"sub_categories":[],"readme":"# snapshot-fs\n\n\u003e Create a snapshot of a directory for use with `memfs`\n\u003e\n\u003e ![snapshot-fs logo](https://github.com/boneskull/snapshot-fs/raw/main/assets/logo-128.png)\n\n## About\n\nI wanted something to help convert directories of test fixtures on-disk to a format usable by an in-memory filesystem ([memfs][]).\n\nTo that end, the `snapshot-fs` package ships a CLI, `snapshot-fs`, which converts a directory tree to a [Compact JSON][], [CBOR][] or [DirectoryJSON][] snapshot for use with `memfs`.\n\n## 🎁 _New in v5.0.0_\n\n- The command-line options have changed; see [Usage](#usage) below.\n- The default input/output format is now CJSON.\n- CBOR snapshots are now supported.\n- The `export` subcommand got a `--dry-run` flag.\n\n## 🎁 _New in v2.0.0_\n\n- The command-line options have changed; see [Usage](#usage) below.\n- `snapshot-fs` can now re-create a directory on the filesystem from a _JSON snapshot_.\n- `loadSnapshot()` is now `readSnapshot()`\n- Export functionality exposed via `exportSnapshot()`\n\n## Install\n\n**`snapshot-fs` requires Node.js v22.13.0 or newer.**\n\n`snapshot-fs` can be run via `npx snapshot-fs` or installed globally via `npm install -g snapshot-fs`. Or however else you want to consume it.\n\n`snapshot-fs` exports both CommonJS and ES modules.\n\n## Usage\n\n```text\nsnapshot-fs [dest]\n\nCreate memfs snapshot from filesystem\n\nCommands:\n  snapshot-fs create [dest]             Create memfs snapshot from filesystem\n                                                                       [default]\n  snapshot-fs export \u003csnapshot\u003e [dest]  Export a JSON snapshot to the filesystem\n\nOutput:\n      --separator, --sep  Path separator\n                                  [choices: \"posix\", \"win32\"] [default: \"posix\"]\n  -f, --format            Snapshot format\n                  [string] [choices: \"cbor\", \"cjson\", \"json\"] [default: \"cjson\"]\n\nPositionals:\n  dest  Path to output file\n\nInput:\n  -s, --source  File or directory to snapshot\n                                         [string] [default: (current directory)]\n\nOptions:\n      --version  Show version number                                   [boolean]\n      --help     Show help                                             [boolean]\n\nFor more information, visit https://github.com/boneskull/snapshot-fs\n```\n\nWhen run without a subcommand, `create` will be invoked.\n\n### `create` w/ [Compact JSON][] Snapshots\n\nBy default (as of v5.0.0), `snapshot-fs` will create a snapshot in [CJSON/Compact JSON][Compact JSON] format.\n\n```sh\nsnapshot-fs --source /some/dir /path/to/output.json\n```\n\nThis is equivalent to:\n\n```sh\nsnapshot-fs create --source /some/dir /path/to/output.json --format=cjson\n```\n\nIn your code, you can use the resulting file using `memfs` directly:\n\n```ts\nimport { type JsonUint8Array, type SnapshotNode, fromJsonSnapshot } from 'memfs/lib/snapshot/index.js';\nimport { memfs } from 'memfs';\n\nconst data = (await readFile(\n  '/path/to/output.json',\n)) as unknown as JsonUint8Array\u003cSnapshotNode\u003e;\n\nconst {vol} = memfs()\nawait fromJsonSnapshot(data, fs: vol.promises);\n\nconsole.log(vol.toTree());\n\n// ... do your thing\n```\n\n...or you can use the `readCJSONSnapshot()` helper from `snapshot-fs`:\n\n```ts\nimport type { JsonUint8Array, SnapshotNode } from 'memfs/lib/snapshot/index.js';\nimport { readCJSONSnapshot } from 'snapshot-fs';\n\nconst data = (await readFile(\n  '/path/to/output.json',\n)) as unknown as JsonUint8Array\u003cSnapshotNode\u003e;\n\nconst vol = await readCJSONSnapshot(data);\n\nconsole.log(vol.toTree());\n```\n\nThis is fast; `JSON.parse()` is never called!\n\n(but we can get faster...)\n\n### `create` w/ [CBOR][] Snapshots\n\nSimilar to the above, you can create a CBOR-formatted snapshot this way:\n\n```sh\nsnapshot-fs --source /some/dir /path/to/output.json --format=cbor\n```\n\nIn your code, you can use the resulting file using `memfs` directly:\n\n```ts\nimport { type SnapshotNode, fromBinarySnapshot } from 'memfs/lib/snapshot/index.js';\nimport type { CborUint8Array } from '@jsonjoy.com/json-pack/lib/cbor/types.js';\nimport { memfs } from 'memfs';\n\nconst data = (await readFile(\n  '/path/to/output.json',\n)) as unknown as CborUint8Array\u003cSnapshotNode\u003e;\n\nconst {vol} = memfs()\nawait fromBinarySnapshot(data, fs: vol.promises);\n\nconsole.log(vol.toTree());\n\n// ... do your thing\n```\n\n...or you can use the `readCBORSnapshot()` helper from `snapshot-fs`:\n\n```ts\nimport {\n  type SnapshotNode,\n  fromBinarySnapshot,\n} from 'memfs/lib/snapshot/index.js';\nimport type { CborUint8Array } from '@jsonjoy.com/json-pack/lib/cbor/types.js';\nimport { readCBORSnapshot } from 'snapshot-fs';\n\nconst data = (await readFile(\n  '/path/to/output.json',\n)) as unknown as CborUint8Array\u003cSnapshotNode\u003e;\n\nconst vol = await readCBORSnapshot(data);\n\nconsole.log(vol.toTree());\n```\n\n### `create` w/ `DirectoryJSON` Snapshots\n\n\u003e [!CAUTION]\n\u003e\n\u003e `DirectoryJSON` is somewhat lossy and should be avoided if you ever want to re-create snapshots on your _real_ filesystem (e.g., using [export](#export)). For a directory full of text files, this is fine; for anything else, use CJSON or CBOR.\n\n```sh\nsnapshot-fs --source /some/dir /path/to/output.json --format=json\n```\n\nThis can be read into a `memfs` `Volume` like so:\n\n```js\nimport { readFile } from 'node:fs/promises';\nimport { memfs } from 'memfs';\n\nconst directoryJson = JSON.parse(\n  await readFile('/path/to/output.json', 'utf8'),\n);\n\nconst { vol } = memfs();\nvol.fromJSON(directoryJson);\n```\n\n### `export`\n\nThis allows you to re-create a directory on the filesystem from a snapshot. Handy!\n\n```text\nsnapshot-fs export \u003csnapshot\u003e [dest]\n\nExport a JSON snapshot to the filesystem\n\nPositionals:\n  snapshot  Path to snapshot file (CBOR/CJSON/DirectoryJSON)          [required]\n  dest      Destination directory           [default: Current working directory]\n\nOutput:\n      --separator, --sep  Path separator\n                                  [choices: \"posix\", \"win32\"] [default: \"posix\"]\n\nOptions:\n      --version  Show version number                                   [boolean]\n      --help     Show help                                             [boolean]\n  -D, --dry-run  Print what would be written to the filesystem         [boolean]\n  -f, --format   Snapshot format\n                  [string] [choices: \"cbor\", \"cjson\", \"json\"] [default: \"cjson\"]\n```\n\nIf you have a snapshot (either format) and you want to re-create snapshot on the filesystem, use the `export` subcommand:\n\n```sh\nsnapshot-fs export /path/to/snapshot.json /path/to/output\n```\n\nThe destination directory will be created if it doesn't exist.\n\n\u003e [!TIP]\n\u003e\n\u003e Use the `--dry-run` flag with `export` to see what would be written to the filesystem.\n\n## API\n\nSome potentially-useful stuff exported from `snapshot-fs`:\n\n- `createSnapshot()`/`createDirectoryJSONSnapshot()`/`createCJSONSnapshot()`/`createCBORSNapshot()` - Create a JSON snapshot from a real or virtual FS\n- `readSnapshot()`/`readDirectoryJSONSnapshot()`/`readCBORSnapshot()`/`readCJSONSnapshot()` - Read a snapshot from a file and load it into a real or virtual FS\n- `exportSnapshot()` - Alias for `readSnapshot()` defaulting to the real FS\n\nSee the typings for more information.\n\n## License\n\nCopyright 2024 [Christopher Hiller](https://github.com/boneskull). Licensed Apache-2.0\n\n[memfs]: https://npm.im/memfs\n[Compact JSON]: https://jsonjoy.com/specs/compact-json\n[CBOR]: https://en.wikipedia.org/wiki/CBOR\n[DirectoryJSON]: https://github.com/streamich/memfs/blob/2c6a6ca55ad2e661f40e488fe5ea4087438bae0e/src/volume.ts#L196-L198\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboneskull%2Fsnapshot-fs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboneskull%2Fsnapshot-fs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboneskull%2Fsnapshot-fs/lists"}