{"id":18573902,"url":"https://github.com/basedwon/mimetics","last_synced_at":"2025-07-15T16:10:20.235Z","repository":{"id":182433812,"uuid":"668493380","full_name":"basedwon/mimetics","owner":"basedwon","description":"Mimetics determines the file type, MIME type, and media type of a given file using magic numbers and content analysis to detect the most likely file type and then maps that to the appropriate MIME and media type.","archived":false,"fork":false,"pushed_at":"2023-10-06T03:29:14.000Z","size":381,"stargazers_count":5,"open_issues_count":4,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-29T01:38:19.155Z","etag":null,"topics":["filetype","magicbytes"],"latest_commit_sha":null,"homepage":"","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/basedwon.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"docs/contributing.md","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":"2023-07-20T00:25:13.000Z","updated_at":"2024-08-20T11:23:28.000Z","dependencies_parsed_at":"2024-06-21T03:16:50.086Z","dependency_job_id":"dda89d4e-e07e-4df3-bf9f-92e18a6123a8","html_url":"https://github.com/basedwon/mimetics","commit_stats":null,"previous_names":["basedwon/mimetics"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fmimetics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fmimetics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fmimetics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fmimetics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basedwon","download_url":"https://codeload.github.com/basedwon/mimetics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223430221,"owners_count":17143625,"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":["filetype","magicbytes"],"created_at":"2024-11-06T23:13:21.286Z","updated_at":"2024-11-06T23:13:21.863Z","avatar_url":"https://github.com/basedwon.png","language":"JavaScript","readme":"# Mimetics\n\n\u003e Know thy files\n\n[![npm](https://img.shields.io/npm/v/mimetics?style=flat\u0026logo=npm)](https://www.npmjs.com/package/mimetics)\n[![pipeline](https://gitlab.com/basedwon/mimetics/badges/master/pipeline.svg)](https://gitlab.com/basedwon/mimetics/-/pipelines)\n[![license](https://img.shields.io/npm/l/mimetics)](https://gitlab.com/basedwon/mimetics/-/blob/master/LICENSE)\n[![downloads](https://img.shields.io/npm/dw/mimetics)](https://www.npmjs.com/package/mimetics) \n\n[![Gitlab](https://img.shields.io/badge/Gitlab%20-%20?logo=gitlab\u0026color=%23383a40)](https://gitlab.com/basedwon/mimetics)\n[![Github](https://img.shields.io/badge/Github%20-%20?logo=github\u0026color=%23383a40)](https://github.com/basedwon/mimetics)\n[![Twitter](https://img.shields.io/badge/@basdwon%20-%20?logo=twitter\u0026color=%23383a40)](https://twitter.com/basdwon)\n[![Discord](https://img.shields.io/badge/Basedwon%20-%20?logo=discord\u0026color=%23383a40)](https://discordapp.com/users/basedwon)\n\nMimetics identifies file types based on magic bytes, patterns, and other unique file attributes. It provides an intuitive API for both synchronous and asynchronous file type detection, supporting various file formats including text, image, audio, video, and archive types.\n\n## Installation\n\nTo add Mimetics to your project, use:\n\n```bash\nnpm install mimetics\n```\n\n## Usage\n\nMimetics allows you to detect file types from file buffers, file names, and even File objects in browser environments. You can also extend its functionality by adding custom definitions.\n\n### Basic Example\n\n```javascript\nconst Mimetics = require('mimetics')\nconst fs = require('fs')\n\n// Load a buffer from a file (e.g., sample.txt)\nconst buffer = fs.readFileSync('sample.txt')\nconst mimetics = new Mimetics()\n\n// Synchronous file type detection\nconst fileType = mimetics.parse(buffer)\nconsole.log(fileType) // Output: { tag: 'text', type: 'text', ext: 'txt', mime: 'text/plain' }\n\n// Asynchronous file type detection (for ZIP files, etc.)\nmimetics.parseAsync(buffer).then(fileType =\u003e {\n  console.log(fileType)\n})\n```\n\n### Adding Custom Definitions\n\nYou can extend Mimetics with custom definitions for additional file types.\n\n```javascript\n\nconst Mimetics = require('mimetics')\n\nconst customDefinitions = [\n  {\n    tag: 'custom',\n    type: 'myfiletype',\n    ext: 'myft',\n    mime: 'application/x-myfiletype',\n    magic: [0x12, 0x34, 0x56],\n    pattern: /^MYFILE/i,\n  }\n]\n\nconst mimetics = new Mimetics()\nmimetics.addDefinitions(customDefinitions)\n\nconst buffer = /* load a buffer for a custom file type */\nconst fileType = mimetics.parse(buffer)\nconsole.log(fileType) // Output should match custom definition\n```\n\n### Browser Example\n\n```javascript\nconst Mimetics = require('mimetics')\n\nconst fileInput = document.querySelector('#fileInput')\nfileInput.addEventListener('change', async (event) =\u003e {\n  const file = event.target.files[0]\n  const mimetics = new Mimetics()\n  \n  const fileType = await mimetics.fromFile(file)\n  console.log(fileType) // Output: file type information\n})\n```\n\n## Supported File Types\n\nMimetics currently supports a variety of formats, including but not limited to:\n\n- **Text**: Plain text (`txt`), Markdown (`md`), LaTeX (`tex`), RTF (`rtf`)\n- **Image**: JPEG (`jpg`, `jpeg`), PNG (`png`), GIF (`gif`), BMP (`bmp`), ICON (`ico`), WebP (`webp`), PDF (`pdf`), SVG (`svg`)\n- **Audio**: MP3 (`mp3`), OGG (`ogg`), WAV (`wav`)\n- **Video**: MP4 (`mp4`), QuickTime (`mov`), AVI (`avi`), MKV (`mkv`), WebM (`webm`), FLV (`flv`)\n- **Archive**: ZIP (`zip`), RAR (`rar`), GZIP (`gz`), 7ZIP (`7z`)\n- **Ebook**: EPUB (`epub`)\n\n## API Reference\n\n### `parse(buffer, name)`\n\nSynchronously parses a buffer to identify the file type.\n\n- **Parameters**:\n  - `buffer` (Uint8Array | ArrayBuffer): The file buffer to parse.\n  - `name` (string, optional): The file name, which can help in detection.\n\n- **Returns**: File type object or `null` if no match is found.\n\n### `parseAsync(buffer, name)`\n\nAsynchronously parses a buffer to identify the file type, with support for ZIP archive analysis.\n\n- **Parameters**:\n  - `buffer` (Uint8Array | ArrayBuffer): The file buffer to parse.\n  - `name` (string, optional): The file name, which can assist in detection.\n\n- **Returns**: A promise resolving to a file type object or `null` if no match is found.\n\n### `fromName(filePath)`\n\nDetermines file type based on the file name extension.\n\n- **Parameters**:\n  - `filePath` (string): The file path or name.\n\n- **Returns**: File type object based on the file extension or `null` if no match is found.\n\n### `fromFile(file)`\n\nAsynchronously determines the file type from a File object (for browser use).\n\n- **Parameters**:\n  - `file` (File): File object to analyze.\n\n- **Returns**: A promise resolving to a file type object.\n\n### `addDefinitions(definitions)`\n\nAdds custom file definitions to the existing set.\n\n- **Parameters**:\n  - `definitions` (Array\u003cObject\u003e): Array of custom file definitions to add, with each object containing properties like `tag`, `type`, `ext`, `mime`, `magic`, and `pattern`.\n\n\nFor more detailed API documentation, see the [API reference](docs/api.md) and the comments in the code.\n\n## Contributing\n\nContributions are welcome. Submit a Pull Request or open an Issue to discuss any changes. Please read [contributing.md](docs/contributing.md) for details on our code of conduct, and the process for submitting merge requests to us.\n\n## Testing\n\nMimetics includes a test suite built with [testr](https://npmjs.com/package/@basd/testr).\n\nTo run the test, first clone the respository:\n\n```sh\ngit clone https://github.com/basedwon/mimetics.git\n```\n\nInstall the dependencies, then run `npm test`:\n\n```bash\nnpm install\nnpm test\n```\n\n## Donations\n\nIf you find this project useful and want to help support further development, please send us some coin. We greatly appreciate any and all contributions. Thank you!\n\n**Bitcoin (BTC):**\n```\n1JUb1yNFH6wjGekRUW6Dfgyg4J4h6wKKdF\n```\n\n**Monero (XMR):**\n```\n46uV2fMZT3EWkBrGUgszJCcbqFqEvqrB4bZBJwsbx7yA8e2WBakXzJSUK8aqT4GoqERzbg4oKT2SiPeCgjzVH6VpSQ5y7KQ\n```\n\n## License\n\nMimetics is [MIT licensed](./LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedwon%2Fmimetics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasedwon%2Fmimetics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedwon%2Fmimetics/lists"}