{"id":15662172,"url":"https://github.com/azu/file-cache","last_synced_at":"2025-04-09T19:21:18.425Z","repository":{"id":45756500,"uuid":"512459291","full_name":"azu/file-cache","owner":"azu","description":"Node.js library that provide a cache for file metadata or file content.","archived":false,"fork":false,"pushed_at":"2025-01-01T10:23:53.000Z","size":901,"stargazers_count":21,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T18:12:36.992Z","etag":null,"topics":["cache","library","nodejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/azu.png","metadata":{"funding":{"github":"azu"},"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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-10T14:41:59.000Z","updated_at":"2025-01-17T15:28:53.000Z","dependencies_parsed_at":"2024-01-20T08:53:15.120Z","dependency_job_id":"14a011e4-e44a-43fd-ac78-5695ff4348ce","html_url":"https://github.com/azu/file-cache","commit_stats":{"total_commits":69,"total_committers":4,"mean_commits":17.25,"dds":"0.10144927536231885","last_synced_commit":"bbbb0e0292086d787b917a3096db20f545f95e41"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Ffile-cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Ffile-cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Ffile-cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Ffile-cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azu","download_url":"https://codeload.github.com/azu/file-cache/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595334,"owners_count":20963943,"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":["cache","library","nodejs"],"created_at":"2024-10-03T13:30:28.503Z","updated_at":"2025-04-09T19:21:18.381Z","avatar_url":"https://github.com/azu.png","language":"TypeScript","funding_links":["https://github.com/sponsors/azu"],"categories":[],"sub_categories":[],"readme":"# @file-cache\n\nA cache library for file metadata or file content.\n\nIt is useful for process that work a given series of files and that only need to repeat the job on the changed ones\nsince the previous run of the process.\n\n## When to update the cache\n\n- When the source code changes.\n- When the source code metadata changes.\n- When the dependencies change.\n- When the configuration changes.\n\n`@file-cache` package help you to implement `--cache` for your tools.\n\n## Installation\n\n```\nnpm install @file-cache/core @file-cache/npm\n```\n\n## Usage\n\nDo heavy tasks for only changed files.\n\n```js\nimport { createCache } from \"@file-cache/core\";\nimport { createNpmPackageKey } from \"@file-cache/npm\"\n\nconst prettierConfig = {/* ... */ };\nconst cache = await createCache({\n    name: \"prettier\",\n    // Use hash value of the content for detecting changes \n    mode: \"content\", // or \"metadata\"\n    // create key for cache\n    keys: [\n        // use dependency(version) as cache key\n        () =\u003e createNpmPackageKey([\"prettier\"]),\n        // use custom key\n        () =\u003e {\n            return JSON.stringify(prettierConfig);\n        }\n    ],\n    noCache: process.env.NO_CACHE_YOUR_TOOL === \"true\" // disable cache by the flag\n});\n\nconst targetFiles = [\"a.js\", \"b.js\", \"c.js\"];\nconst doHeavyTask = (filePath) =\u003e {\n    // do heavy task\n}\nfor (const targetFile of targetFiles) {\n    const result = await cache.getAndUpdateCache(targetFile);\n    if (result.error) {\n        throw result.error\n    }\n    if (!result.changed) {\n        continue; // no need to update\n    }\n    doHeavyTask(targetFile);\n}\n// write cache state to file for persistence\nawait cache.reconcile();\n```\n\n**Examples:**\n\n- https://github.com/azu/file-cache-demo\n\n**Options:**\n\nSee [package/core](packages/core) documentation.\n\n## Advanced Usage\n\nIf your tool has a plugin system, you can use [`@file-cache/package-lock`](./packages/package-lock) for caching plugin's dependencies.\nThis package use `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb` as cache key.\n\n```\nnpm install @file-cache/core @file-cache/npm @file-cache/package-lock\n```\n\n```js\nimport { createCache } from \"@file-cache/core\";\nimport { createNpmPackageKey } from \"@file-cache/npm\"\nimport { createPackageLockKey } from \"@file-cache/package-lock\"\n\nconst yourConfig = {/* ... */ };\nconst cache = await createCache({\n    name: \"your-tool\",\n    // Use hash value of the content for detecting changes \n    mode: \"content\", // or \"metadata\"\n    // create key for cache\n    keys: [\n        // use your tool version as cache key\n        () =\u003e createNpmPackageKey([\"your-tool\"]),\n        // use dependency as cache key\n        () =\u003e createPackageLockKey(process.cwd()), // search process.cwd()/package-lock.json\n        // use config as cache key\n        () =\u003e {\n            return JSON.stringify(yourConfig);\n        }\n    ],\n    noCache: process.env.NO_CACHE_YOUR_TOOL === \"true\" // disable cache by the flag\n});\n```\n\n## Cache Mechanism\n\nCache file directory:\n\n:memo: You can change the directory by `cacheDirectory` option.\n\n```\n|- node_modules\n  |- .cache\n    |- \u003cpkg-name\u003e\n      |- \u003chash-of-cache-key\u003e-\u003cmode\u003e\n```\n\n- Related: [sindresorhus/find-cache-dir: Finds the common standard cache directory](https://github.com/sindresorhus/find-cache-dir)\n\nCache file structure:\n\n```markdown\n{\n    \"file-path\": \u003cresult\u003e\n}\n```\n\nThis library does not clean up previous cache files.\nWhen the `\u003chash-of-cache-key\u003e` is changed, the previous cache file will not be deleted automatically.\n\n## Users\n\n- [azu/create-validator-ts: Create JSON Schema validator from TypeScript.](https://github.com/azu/create-validator-ts)\n\n## Release flow\n\n    npm run versionup:* \u0026\u0026 npm run release \u0026\u0026 git add . \u0026\u0026 git commit -m \"update lock\" \u0026\u0026 git push --tags\n\n## Related\n\n- [royriojas/file-entry-cache](https://github.com/royriojas/file-entry-cache)\n    - Inspired by this project\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazu%2Ffile-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazu%2Ffile-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazu%2Ffile-cache/lists"}