diff --git a/docs/js.md b/docs/js.md index aedd5447..9bc83ed4 100644 --- a/docs/js.md +++ b/docs/js.md @@ -1,3 +1,191 @@ ### Table of Contents + +* [MagikaNode][1] + * [load][2] + * [Parameters][3] + * [identifyStream][4] + * [Parameters][5] + * [identifyStreamFull][6] + * [Parameters][7] +* [Magika][8] + * [load][9] + * [Parameters][10] + * [identifyBytesFull][11] + * [Parameters][12] + * [identifyBytes][13] + * [Parameters][14] + +## MagikaNode + +[js/magika\_node.ts:29-113][15] + +**Extends Magika** + +The main Magika object for Node use. + +Example usage: + +```js +import { readFile } from "fs/promises"; +import { MagikaNode as Magika } from "magika"; +const data = await readFile("some file"); +const magika = new Magika(); +await magika.load(); +const prediction = await magika.identifyBytes(data); +console.log(prediction); +``` + +For a client-side implementation, please import `Magika` instead. + +Demos: + +* Node: `/js/index.js`, which you can run with `yarn run bin -h`. +* Client-side: see `/website/src/components/FileClassifierDemo.vue` + +### load + +[js/magika\_node.ts:45-58][16] + +Loads the Magika model and config from URLs. + +#### Parameters + +* `options` **MagikaOptions** The urls or file paths where the model and its config are stored.Parameters are optional. If not provided, the model will be loaded from GitHub. + +Returns **[Promise][17]\** + +### identifyStream + +[js/magika\_node.ts:66-69][18] + +Identifies the content type from a read stream + +#### Parameters + +* `stream` **ReadStream** A read stream +* `length` **[number][19]** Total length of stream data (this is needed to find the middle without keep the file in memory) + +Returns **[Promise][17]\** A dictionary containing the top label and its score, + +### identifyStreamFull + +[js/magika\_node.ts:77-80][20] + +Identifies the content type from a read stream + +#### Parameters + +* `stream` **ReadStream** A read stream +* `length` **[number][19]** Total length of stream data (this is needed to find the middle without keep the file in memory) + +Returns **[Promise][17]\** A dictionary containing the top label, its score, and a list of content types and their scores. + +## Magika + +[js/magika.ts:27-123][21] + +The main Magika object for client-side use. + +Example usage: + +```js +const file = new File(["# Hello I am a markdown file"], "hello.md"); +const fileBytes = new Uint8Array(await file.arrayBuffer()); +const magika = new Magika(); +await magika.load(); +const prediction = await magika.identifyBytes(fileBytes); +console.log(prediction); +``` + +For a Node implementation, please import `MagikaNode` instead. + +Demos: + +* Node: `/js/index.js`, which you can run with `yarn run bin -h`. +* Client-side: see `/website/src/components/FileClassifierDemo.vue` + +### load + +[js/magika.ts:52-57][22] + +Loads the Magika model and config from URLs. + +#### Parameters + +* `options` **MagikaOptions** The urls where the model and its config are stored.Parameters are optional. If not provided, the model will be loaded from GitHub. + +Returns **[Promise][17]\** + +### identifyBytesFull + +[js/magika.ts:64-67][23] + +Identifies the content type of a byte array, returning all probabilities instead of just the top one. + +#### Parameters + +* `fileBytes` **any** a Buffer object (a fixed-length sequence of bytes) + +Returns **[Promise][17]\** A dictionary containing the top label, its score, and a list of content types and their scores. + +### identifyBytes + +[js/magika.ts:74-77][24] + +Identifies the content type of a byte array. + +#### Parameters + +* `fileBytes` **any** a Buffer object (a fixed-length sequence of bytes) + +Returns **[Promise][17]\** A dictionary containing the top label and its score + +[1]: #magikanode + +[2]: #load + +[3]: #parameters + +[4]: #identifystream + +[5]: #parameters-1 + +[6]: #identifystreamfull + +[7]: #parameters-2 + +[8]: #magika + +[9]: #load-1 + +[10]: #parameters-3 + +[11]: #identifybytesfull + +[12]: #parameters-4 + +[13]: #identifybytes + +[14]: #parameters-5 + +[15]: https://github.com/google/magika/blob/f270641b2ed048f8ba7b454f0dcf3c32b8f5a27a/js/magika_node.ts#L29-L113 "Source code on GitHub" + +[16]: https://github.com/google/magika/blob/f270641b2ed048f8ba7b454f0dcf3c32b8f5a27a/js/magika_node.ts#L45-L58 "Source code on GitHub" + +[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise + +[18]: https://github.com/google/magika/blob/f270641b2ed048f8ba7b454f0dcf3c32b8f5a27a/js/magika_node.ts#L66-L69 "Source code on GitHub" + +[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number + +[20]: https://github.com/google/magika/blob/f270641b2ed048f8ba7b454f0dcf3c32b8f5a27a/js/magika_node.ts#L77-L80 "Source code on GitHub" + +[21]: https://github.com/google/magika/blob/f270641b2ed048f8ba7b454f0dcf3c32b8f5a27a/js/magika.ts#L27-L123 "Source code on GitHub" + +[22]: https://github.com/google/magika/blob/f270641b2ed048f8ba7b454f0dcf3c32b8f5a27a/js/magika.ts#L52-L57 "Source code on GitHub" + +[23]: https://github.com/google/magika/blob/f270641b2ed048f8ba7b454f0dcf3c32b8f5a27a/js/magika.ts#L64-L67 "Source code on GitHub" + +[24]: https://github.com/google/magika/blob/f270641b2ed048f8ba7b454f0dcf3c32b8f5a27a/js/magika.ts#L74-L77 "Source code on GitHub"