{"id":17491821,"url":"https://github.com/nuintun/koa-files","last_synced_at":"2025-04-22T20:24:16.589Z","repository":{"id":36472622,"uuid":"227047029","full_name":"nuintun/koa-files","owner":"nuintun","description":"A static files serving middleware for koa.","archived":false,"fork":false,"pushed_at":"2025-04-14T07:32:15.000Z","size":105328,"stargazers_count":8,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-14T08:38:34.836Z","etag":null,"topics":["koa","middleware","send","serve","server","service","static"],"latest_commit_sha":null,"homepage":"https://github.com/nuintun/koa-files","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/nuintun.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-10T06:40:09.000Z","updated_at":"2025-04-14T07:32:19.000Z","dependencies_parsed_at":"2024-11-12T04:01:31.425Z","dependency_job_id":null,"html_url":"https://github.com/nuintun/koa-files","commit_stats":{"total_commits":301,"total_committers":2,"mean_commits":150.5,"dds":"0.0033222591362126463","last_synced_commit":"dc9b4a91348238976a2bf160e7fb40963783fffe"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuintun%2Fkoa-files","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuintun%2Fkoa-files/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuintun%2Fkoa-files/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuintun%2Fkoa-files/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nuintun","download_url":"https://codeload.github.com/nuintun/koa-files/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248851694,"owners_count":21171834,"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":["koa","middleware","send","serve","server","service","static"],"created_at":"2024-10-19T08:05:16.130Z","updated_at":"2025-04-22T20:24:16.570Z","avatar_url":"https://github.com/nuintun.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# koa-files\n\n\u003c!-- prettier-ignore --\u003e\n\u003e A static files serving middleware for koa.\n\u003e\n\u003e [![NPM Version][npm-image]][npm-url]\n\u003e [![Download Status][download-image]][npm-url]\n\u003e [![Languages Status][languages-image]][github-url]\n\u003e ![Node Version][node-image]\n\u003e [![License][license-image]][license-url]\n\n## Installation\n\n```bash\n$ npm install koa-files\n```\n\n## API\n\n```ts\nimport { Middleware } from 'koa';\nimport fs, { Stats } from 'node:fs';\n\ninterface Headers {\n  [key: string]: string | string[];\n}\n\ninterface IgnoreFunction {\n  (path: string): boolean | Promise\u003cboolean\u003e;\n}\n\ninterface HeadersFunction {\n  (path: string, stats: Stats): Promise\u003cHeaders | void\u003e | Headers | void;\n}\n\nexport interface FileSystem {\n  stat: typeof fs.stat;\n  open: typeof fs.open;\n  read: typeof fs.read;\n  close: typeof fs.close;\n}\n\nexport interface Options {\n  fs?: FileSystem;\n  defer?: boolean;\n  etag?: boolean;\n  acceptRanges?: boolean;\n  lastModified?: boolean;\n  highWaterMark?: number;\n  ignore?: IgnoreFunction;\n  headers?: Headers | HeadersFunction;\n}\n\nexport function server(root: string, options?: Options): Middleware;\n```\n\n### root\n\n- Root directory string.\n- Nothing above this root directory can be served.\n\n### Options\n\n##### `fs`\n\n- Defaults to `node:fs`.\n- The file system to used.\n\n##### `defer`\n\n- Defaults to `false`.\n- If true, serves after `await next()`.\n- Allowing any downstream middleware to respond first.\n\n##### `etag`\n\n- Defaults to `true`.\n- Enable or disable etag generation.\n- Use weak etag internally.\n- Can be overridden by the `headers`.\n\n##### `acceptRanges`\n\n- Defaults to `true`.\n- Enable or disable accepting ranged requests.\n- Disabling this will not send Accept-Ranges and ignore the contents of the Range request header.\n- Can be overridden by the `headers`.\n\n##### `lastModified`\n\n- Defaults to `true`.\n- Enable or disable Last-Modified header.\n- Use the file system's last modified value.\n- Can be overridden by the `headers`.\n\n##### `highWaterMark`\n\n- Defaults to `65536` (64 KiB).\n- Set the high water mark for the read stream.\n\n##### `ignore`\n\n- Defaults to `undefined`.\n- Function that determines if a file should be ignored.\n\n##### `headers`\n\n- Defaults to `undefined`.\n- Set headers to be sent.\n- See docs: [Headers in MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).\n\n## Example\n\n```ts\n/**\n * @module server\n * @license MIT\n * @author nuintun\n */\n\nimport Koa from 'koa';\nimport { server } from 'koa-files';\n\nconst app = new Koa();\nconst port = process.env.PORT || 80;\n\n// Static files server\napp.use(\n  server('tests', {\n    headers: {\n      'Cache-Control': 'public, max-age=31557600'\n    }\n  })\n);\n\n/**\n * @function httpError\n * @param {NodeJS.ErrnoException} error\n * @returns {boolean}\n */\nfunction httpError(error) {\n  return /^(EOF|EPIPE|ECANCELED|ECONNRESET|ECONNABORTED)$/i.test(error.code);\n}\n\n// Listen error event\napp.on('error', error =\u003e {\n  !httpError(error) \u0026\u0026 console.error(error);\n});\n\n// Start server\napp.listen(port, () =\u003e {\n  console.log(`\u003e server running at: 127.0.0.1:${port}`);\n});\n```\n\n## Features\n\nSupport multipart range and download resumption.\n\n## License\n\nMIT\n\n[npm-image]: https://img.shields.io/npm/v/koa-files.svg?style=flat-square\n[npm-url]: https://www.npmjs.org/package/koa-files\n[download-image]: https://img.shields.io/npm/dm/koa-files.svg?style=flat-square\n[languages-image]: https://img.shields.io/github/languages/top/nuintun/koa-files?style=flat-square\n[github-url]: https://github.com/nuintun/koa-files\n[node-image]: https://img.shields.io/node/v/koa-files.svg?style=flat-square\n[license-image]: https://img.shields.io/github/license/nuintun/koa-files?style=flat-square\n[license-url]: https://github.com/nuintun/koa-files/blob/main/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuintun%2Fkoa-files","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnuintun%2Fkoa-files","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuintun%2Fkoa-files/lists"}