Change .getMime to .detect (#38)

This was done for a couple of reasons. As features have been added to
WASMagic, the method name `.getMime` is no longer accurate. The user
can get any number of available features from the passed `Buffer`.
Second, consistency. Several other `libmagic` based libraries used the
`.detect` method (though the signatures differ).

While on the surface this looks like a BREAKING CHANGE, it is not. The
original `.getMime` method passes through to `.detect`. Though, it has
been marked as deprecated.

Makefile

@@ -22,7 +22,7 @@ dist/index.js: $(ts_files) dist/libmagic-wrapper.js
 dist/libmagic-wrapper.js: src/libmagic-wrapper.c dist/magic.mgc dist/libmagic.so dist/libmagic-wrapper.d.ts
 	emcc -s MODULARIZE -s WASM=1 \
 	-s EXPORTED_RUNTIME_METHODS='["ccall", "cwrap", "FS"]' \
-	-s EXPORTED_FUNCTIONS='["_magic_wrapper_load", "_magic_wrapper_get_mime", "_malloc", "_free"]' \
+	-s EXPORTED_FUNCTIONS='["_magic_wrapper_load", "_magic_wrapper_detect", "_malloc", "_free"]' \
 	-s ALLOW_MEMORY_GROWTH=1 \
 	--pre-js ./src/pre.js \
 	--embed-file ./dist/magic.mgc@/magic/magic.mgc \

README.md

@@ -25,7 +25,7 @@ import { WASMagic } from "wasmagic";
 const magic = await WASMagic.create();
 
 const pngFile = Buffer.from("89504E470D0A1A0A0000000D49484452", "hex");
-console.log(magic.getMime(pngFile));
+console.log(magic.detect(pngFile));
 // outputs: image/png
 ```
 
@@ -37,7 +37,7 @@ const { WASMagic } = require("wasmagic");
 async function main() {
   const magic = await WASMagic.create();
   const pngFile = Buffer.from("89504E470D0A1A0A0000000D49484452", "hex");
-  console.log(magic.getMime(pngFile));
+  console.log(magic.detect(pngFile));
 }
 
 main().catch((err) => console.error(err));
@@ -88,7 +88,7 @@ const magic = await WASMagic.create({
 });
 
 const pngFile = Buffer.from("89504E470D0A1A0A0000000D49484452", "hex");
-console.log(magic.getMime(pngFile));
+console.log(magic.detect(pngFile));
 // outputs: image/png; charset=binary
 ```
 
@@ -130,7 +130,7 @@ const magic = await WASMagic.create({
 });
 
 console.log(
-  magic.getMime(
+  magic.detect(
     Buffer.from(
       `FOOBARFILETYPE
 
@@ -167,7 +167,7 @@ output)
 You should instantiate as few copies of `WASMagic` as you can get away with for
 your use case. Each instantiation loads the magic database, which is around 8MB.
 One instance per process / worker thread should be enough as the main api
-(`WASMagic.getMime`) is synchronous.
+(`WASMagic.detect`) is synchronous.
 
 If you want to offload processing to another thread (and in production workloads
 you probably should be), take a look at the [Async / Worker
@@ -190,7 +190,7 @@ const magicPromise = WASMagic.create().then((instance) => {
 async function main() {
   const magic = magicGlobal || (await magicPromise);
   const pngFile = Buffer.from("89504E470D0A1A0A0000000D49484452", "hex");
-  console.log(magic.getMime(pngFile));
+  console.log(magic.detect(pngFile));
 }
 
 main().catch((err) => console.error(err));
@@ -218,7 +218,7 @@ const { bytesRead, buffer } = await file.read({ buffer: Buffer.alloc(1024) });
 
 // We're assuming that largeFile.mp4 is >= 1024 bytes in size and our buffer
 // will only have the first 1024 bytes of largeFile.mp4 in it
-console.log(magic.getMime(buffer));
+console.log(magic.detect(buffer));
 await file.close();
 
 // outputs: video/mp4

examples/stream-detection/index.js

@@ -31,7 +31,7 @@ async function init() {
         // Once we receive over 1KB, we can try and get the mime type of the upload
         if (curSize >= 1024) {
           const recieved = Buffer.concat(bufs);
-          detectedMime = magic.getMime(recieved);
+          detectedMime = magic.detect(recieved);
           console.log("Got a:", detectedMime);
           isDetected = true;
           // Send everything we've received to the next stream in the pipe,

examples/worker/worker.mjs

@@ -1,4 +1,4 @@
 import { WASMagic } from "../../dist/index.js";
 const magic = await WASMagic.create();
 
-export default (buf) => magic.getMime(buf);
+export default (buf) => magic.detect(buf);

src/index.ts

@@ -1,6 +1,6 @@
 import libmagicFactory from "../dist/libmagic-wrapper";
 
-declare function wrappedGetMime(bufPointer: number, bufLength: number): string;
+declare function wrappedDetect(bufPointer: number, bufLength: number): string;
 
 export enum WASMagicFlags {
   /** No flags */
@@ -91,7 +91,7 @@ export class WASMagic {
   }
 
   private Module: LibmagicModule;
-  private getMimeFromWasm: typeof wrappedGetMime;
+  private detectFromWasm: typeof wrappedDetect;
 
   private constructor(Module: LibmagicModule, inputOptions: WASMagicOptions) {
     const options = Object.assign({}, defaultWASMagicOptions, inputOptions);
@@ -130,17 +130,24 @@ export class WASMagic {
     Module.FS.unlink("/magic/magic.mgc");
 
     this.Module = Module;
-    this.getMimeFromWasm = Module.cwrap("magic_wrapper_get_mime", "string", [
+    this.detectFromWasm = Module.cwrap("magic_wrapper_detect", "string", [
       "number",
       "number",
-    ]) as typeof wrappedGetMime;
+    ]) as typeof wrappedDetect;
   }
 
-  getMime(buf: Uint8Array): string {
+  detect(buf: Uint8Array): string {
     const ptr = this.Module._malloc(buf.length);
     this.Module.HEAPU8.set(buf, ptr);
-    const result = this.getMimeFromWasm(ptr, buf.length);
+    const result = this.detectFromWasm(ptr, buf.length);
     this.Module._free(ptr);
     return result;
   }
+
+  /**
+   * @deprecated Use {@link WASMagic#detect} instead
+   */
+  getMime(buf: Uint8Array): string {
+    return this.detect(buf);
+  }
 }

src/libmagic-wrapper.c

@@ -19,7 +19,7 @@ const char* magic_wrapper_load(
   return "";
 }
 
-const char* magic_wrapper_get_mime(const void *buf, size_t nb)
+const char* magic_wrapper_detect(const void *buf, size_t nb)
 {
   return magic_buffer(ms, buf, nb);
 }

src/test/integration/index.ts

@@ -30,8 +30,8 @@ describe("WASMagic", () => {
       const out: string[][] = [];
       for (const file of fileExampleList) {
         const fileBuf = fs.readFileSync(file);
-        const mimeType = magic.getMime(fileBuf);
-        const textType = magicText.getMime(fileBuf);
+        const mimeType = magic.detect(fileBuf);
+        const textType = magicText.detect(fileBuf);
         out.push([
           path.relative(path.resolve(__dirname, "../../../"), file),
           mimeType,
@@ -45,8 +45,8 @@ describe("WASMagic", () => {
       "%s identified as %s",
       (file, expectedOutput, expectedText) => {
         const fileBuf = fs.readFileSync(file);
-        expect(magic.getMime(fileBuf)).toBe(expectedOutput);
-        expect(magicText.getMime(fileBuf)).toBe(expectedText);
+        expect(magic.detect(fileBuf)).toBe(expectedOutput);
+        expect(magicText.detect(fileBuf)).toBe(expectedText);
       },
     );
   });
@@ -63,7 +63,7 @@ describe("WASMagic", () => {
 
     test("FOOBAR file type identified as foobarfiletype", () => {
       expect(
-        magic.getMime(
+        magic.detect(
           Buffer.from(
             `FOOBARFILETYPE
 
@@ -78,7 +78,7 @@ Some made up stuff
     test.each(cases.filter((v) => pngOrJpeg.includes(v[1])))(
       "%s identified as %s",
       (file, expectedOutput) => {
-        expect(magic.getMime(fs.readFileSync(file))).toBe(expectedOutput);
+        expect(magic.detect(fs.readFileSync(file))).toBe(expectedOutput);
       },
     );
   });
@@ -100,15 +100,15 @@ Some made up stuff
     test.each(cases.filter((v) => pngOrJpeg.includes(v[1])))(
       "%s identified as %s",
       (file, expectedOutput) => {
-        expect(magic.getMime(fs.readFileSync(file))).toBe(expectedOutput);
+        expect(magic.detect(fs.readFileSync(file))).toBe(expectedOutput);
       },
     );
 
     const rtfOrHtml = ["text/rtf", "text/html"];
     test.each(cases.filter((v) => rtfOrHtml.includes(v[1])))(
       "%s identified as text/plain",
       (file) => {
-        expect(magic.getMime(fs.readFileSync(file))).toBe("text/plain");
+        expect(magic.detect(fs.readFileSync(file))).toBe("text/plain");
       },
     );
   });