sane-wasm 0.1.2 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # SANE WebAssembly (sane-wasm)
 
-A project to bring the [SANE API](http://www.sane-project.org/intro.html) to the web.
+A project to bring the [SANE API](http://www.sane-project.org/intro.html) to Node.js and the Web using WebAssembly.
 
-Currently, it only supports USB scanners and is only tested on a browser environment (WebUSB).
+It supports USB scanners on browser environments through the [WebUSB API](https://developer.mozilla.org/en-US/docs/Web/API/WebUSB_API) and on Node.js using [node-usb](https://github.com/node-usb/node-usb).
 
 This works by compiling all SANE backends (and required dependencies) to WebAssembly using Emscripten. The other key piece is @RReverser's [bridge from libusb to WebUSB](https://github.com/libusb/libusb/pull/1057) ([1](https://web.dev/porting-libusb-to-webusb/)/[2](https://web.dev/porting-gphoto2-to-the-web/)) with [some patching](https://github.com/goncalomb/sane-wasm/issues/1) to support multi-threading.
 
@@ -10,15 +10,67 @@ Right now, it includes [all backends](http://www.sane-project.org/lists/sane-bac
 
 ## WebScan
 
-**Check [webscan.goncalomb.com](https://webscan.goncalomb.com/) for a demo of sane-wasm.** This is a React application that uses sane-wasm for document/image scanning directly in the browser. Exposes all scanning options to the user for full control.
+**Check [webscan.goncalomb.com](https://webscan.goncalomb.com/) for a demo of sane-wasm.** This is a React application that uses sane-wasm for document/image scanning directly in the browser. It exposes all scanning options to the user for full control.
 
-If you are interested in seeing the compiled output of sane-wasm, check:
+## Usage
 
-* [webscan.goncalomb.com/sane-wasm/](https://webscan.goncalomb.com/sane-wasm/): all files
-* [webscan.goncalomb.com/sane-wasm/libsane.html](https://webscan.goncalomb.com/sane-wasm/libsane.html): test page
+The pre-compiled WebAssembly package for sane-wasm is published on NPM:
+
+https://www.npmjs.com/package/sane-wasm?activeTab=code
+
+### For Web Environments (e.g. Webpack)
+
+```
+npm install -D sane-wasm
+```
+
+The main .js will not be bundled with your application. A loader ([lib/loader.js](https://github.com/goncalomb/sane-wasm/blob/master/lib/loader.js)) is provided to automatically load the .js/.wasm files from a CDN ([jsdelivr.com](https://www.jsdelivr.com/)). You can configure the loader to serve the files from your server if you want.
+
+See [examples/webpack/](https://github.com/goncalomb/sane-wasm/tree/master/examples/webpack) for a working example.
+
+### For Node.js
+
+```
+npm install sane-wasm usb
+```
+
+The usb package ([node-usb](https://github.com/node-usb/node-usb)) is required to provide USB functionality.
+
+See [examples/node/](https://github.com/goncalomb/sane-wasm/tree/master/examples/node) for a working example.
+
+### As Git Submodule (not recommended) / Custom Build
+
+As an alternative, you can add sane-wasm as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to your application and integrate `./build.sh` with your build process. This is not recommended as it relies on some magical/dubious code on `./build.sh` to make the build work.
+
+You can also just build sane-wasm independently and use the build artifacts...
+
+```
+<script src="build/libsane.js"></script>
+<script>
+    window.LibSANE().then(lib => {
+        // your code
+        console.log(lib.sane_init());
+    });
+</script>
+```
+
+```
+const { libsane } = require('./sane-wasm');
+libsane().then(lib => {
+    console.log(lib.sane_init());
+});
+```
+
+```
+import { libsane } from './sane-wasm';
+const lib = await libsane();
+console.log(lib.sane_init());
+```
 
 ## Building
 
+### SANE Only
+
 Building requires [emscripten](https://github.com/emscripten-core/emscripten) and all the required tools to build the dependencies.
 
 The preferred way is just to use the pre-configured Docker image:
@@ -33,7 +85,7 @@ Start the test server with:
 
 Check the test page at: http://localhost:6931/libsane.html.
 
-### build.sh
+#### build.sh
 
 The `./build.sh` script has other options for debugging:
 
@@ -47,26 +99,11 @@ usage: build.sh [options]
   --shell        run debug shell (depends on --with-docker)
 ```
 
-## Using
-
-For now, this project has only been used on a browser environment, usage with Node.js or other environments is untested/unsupported.
-
-The recommended way to use this project is to add it as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to your application. Integrate `./build.sh` with your build process. And include the main .js file:
-
-```
-<script src="build/libsane.js"></script>
-<script>
-    window.LibSANE().then(LibSANE => {
-        window.LibSANE = LibSANE;
-        // your code
-        console.log(LibSANE.sane_init());
-    });
-</script>
-```
+### Full Build (SANE + TypeScript)
 
-This will be improved in the future.
+To do a full build use `npm run build`.
 
-## Exposed API
+## API
 
 Most of the SANE API is exposed as-is. Check the [SANE Standard](https://sane-project.gitlab.io/standard/index.html).
 
@@ -76,12 +113,12 @@ Some safeguards are in place to avoid API misuse and prevent memory leaks. It's
 
 The most important difference with the underlying SANE API is that **device handles are not exposed**. This means that `sane_open()` does not return a device handle. A single handle is managed by the internal code. This effectively means that **only one device can be accessed at a time**. This was a design decision made to simplify the API and prevent other issues.
 
-> Personally, I believe that this is an acceptable change, especially for WebAssembly where it may be easier to lose track of opened resources and crash the application. The SANE API is also somewhat unforgiving and building more safeguards around it (especially with multiple handles) is not worth the effort. Ultimately I don't see a use that requires more than one device open at a time. @goncalomb
+> Personally, I believe that this is an acceptable change, especially for WebAssembly where it may be easier to lose track of opened resources and crash the application. The SANE API is also somewhat unforgiving and building more safeguards around it (especially with multiple handles) is not worth the effort. Ultimately I don't see a use that requires more than one device open at a time. -goncalomb
 
 ### Documentation
 
-For now, check the [libsane.d.ts](libsane.d.ts) for the API declaration.
+Check API documentation at: [goncalomb.github.io/sane-wasm/modules.html](https://goncalomb.github.io/sane-wasm/modules.html).
 
 ## License
 
-Because of the weird state of SANE's licensing (GPL + linking exception, on some backends), see [backends/LICENSE](https://gitlab.com/sane-project/backends/-/blob/master/LICENSE). I'm releasing this project with dual licensing [GNU GPLv2](LICENSE.txt) + [GNU LGPLv2.1](LICENSE-LGPL.txt). IANAL, you choose.
+Because of the weird state of SANE's licensing (GPL + linking exception, on some backends), see [backends/LICENSE](https://gitlab.com/sane-project/backends/-/blob/master/LICENSE). I'm releasing this project with dual licensing [GNU GPLv2](https://github.com/goncalomb/sane-wasm/blob/master/LICENSE.txt) + [GNU LGPLv2.1](https://github.com/goncalomb/sane-wasm/blob/master/LICENSE-LGPL.txt). IANAL, you choose.

package/build/libsane.js

@@ -80,6 +80,7 @@ Module["ready"] = new Promise(function(resolve, reject) {
    obj.__proto__ = this.prototype;
    obj[this.reverseObject] = {};
    Object.keys(obj).forEach(k => {
+    obj[obj[k]] = k;
     obj[this.reverseObject][obj[k]] = k;
    });
   }

package/dist/index.d.ts

@@ -0,0 +1,499 @@
+/**
+ * Equivalent to the SANE API C enum `SANE_Status`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#status-type}
+ */
+export declare enum SANEStatus {
+    GOOD = 0,
+    UNSUPPORTED = 1,
+    CANCELLED = 2,
+    DEVICE_BUSY = 3,
+    INVAL = 4,
+    EOF = 5,
+    JAMMED = 6,
+    NO_DOCS = 7,
+    COVER_OPEN = 8,
+    IO_ERROR = 9,
+    NO_MEM = 10,
+    ACCESS_DENIED = 11
+}
+/**
+ * Equivalent to the SANE API C enum `SANE_Value_Type`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-value-type}
+ */
+export declare enum SANEValueType {
+    BOOL = 0,
+    INT = 1,
+    FIXED = 2,
+    STRING = 3,
+    BUTTON = 4,
+    GROUP = 5
+}
+/**
+ * Equivalent to the SANE API C enum `SANE_Unit`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-value-unit}
+ */
+export declare enum SANEUnit {
+    NONE = 0,
+    PIXEL = 1,
+    BIT = 2,
+    MM = 3,
+    DPI = 4,
+    PERCENT = 5,
+    MICROSECOND = 6
+}
+/**
+ * Equivalent to the SANE API C enum `SANE_Constraint_Type`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-value-constraints}
+ */
+export declare enum SANEConstraintType {
+    NONE = 0,
+    RANGE = 1,
+    WORD_LIST = 2,
+    STRING_LIST = 3
+}
+/**
+ * Equivalent to the SANE API C enum `SANE_Frame`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-get-parameters}
+ */
+export declare enum SANEFrame {
+    GRAY = 0,
+    RGB = 1,
+    RED = 2,
+    GREEN = 3,
+    BLUE = 4
+}
+/**
+ * Library state. This is provided by sane-wasm, it's not part of SANE API.
+ */
+export type SANEState = {
+    /**
+     * Is the library initialized with {@link LibSANE.sane_init}?
+     */
+    initialized: boolean;
+    /**
+     * Version code provided by the last {@link LibSANE.sane_init} call.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#version-control}
+     */
+    version_code: number;
+    /**
+     * Version code (decoded) provided by the last {@link LibSANE.sane_init} call.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#version-control}
+     */
+    version: {
+        major: number;
+        minor: number;
+        build: number;
+    };
+    /**
+     * Is a device open with {@link LibSANE.sane_open}?
+     */
+    open: boolean;
+};
+/**
+ * Equivalent to the SANE API C type `SANE_Device`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#device-descriptor-type}
+ */
+export type SANEDevice = {
+    name: string;
+    vendor: string;
+    model: string;
+    type: string;
+};
+/**
+ * Equivalent to the SANE API C bit mask `SANE_CAP_*`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-capabilities}
+ */
+export type SANECap = {
+    SOFT_SELECT: boolean;
+    HARD_SELECT: boolean;
+    SOFT_DETECT: boolean;
+    EMULATED: boolean;
+    AUTOMATIC: boolean;
+    INACTIVE: boolean;
+    ADVANCED: boolean;
+};
+/**
+ * Equivalent to the SANE API C type `SANE_Range`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-descriptor-type}
+ */
+export type SANERange = {
+    min: number;
+    max: number;
+    quant: number;
+};
+/**
+ * Equivalent to the SANE API C type `SANE_Option_Descriptor`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-descriptor-type}
+ */
+export type SANEOptionDescriptor = {
+    name: string;
+    title: string;
+    desc: string;
+    type: SANEValueType;
+    unit: SANEUnit;
+    size: number;
+    cap: SANECap;
+} & ({
+    constraint_type: SANEConstraintType.NONE;
+    constraint: null;
+} | {
+    constraint_type: SANEConstraintType.RANGE;
+    constraint: SANERange;
+} | {
+    constraint_type: SANEConstraintType.WORD_LIST;
+    constraint: number[];
+} | {
+    constraint_type: SANEConstraintType.STRING_LIST;
+    constraint: string[];
+});
+/**
+ * Equivalent to the SANE API C bit mask `SANE_INFO_*`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-control-option}
+ */
+export type SANEInfo = {
+    INEXACT: boolean;
+    RELOAD_OPTIONS: boolean;
+    RELOAD_PARAMS: boolean;
+};
+/**
+ * Equivalent to the SANE API C type `SANE_Parameters`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-get-parameters}
+ */
+export type SANEParameters = {
+    format: SANEFrame;
+    last_frame: boolean;
+    bytes_per_line: number;
+    pixels_per_line: number;
+    lines: number;
+    depth: number;
+};
+/**
+ * @private Type for enums provided by the core SANE Emscripten module.
+ * @deprecated
+ */
+export type SANEEnum<E, TE> = E & {
+    /**
+     * @deprecated Use reverse map already built into TS enums.
+     */
+    asString: (value: TE) => string;
+};
+/**
+ * The core SANE Emscripten module.
+ */
+export interface LibSANE {
+    /**
+     * Commit hash of sane-wasm.
+     */
+    SANE_WASM_COMMIT: string;
+    /**
+     * Version code of sane-wasm.
+     */
+    SANE_WASM_VERSION: string;
+    /**
+     * List of SANE API backends built into sane-wasm.
+     */
+    SANE_WASM_BACKENDS: string;
+    /**
+     * SANE API version code (major).
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#version-control}
+     */
+    SANE_CURRENT_MAJOR: number;
+    /**
+     * SANE API version code (minor).
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#version-control}
+     */
+    SANE_CURRENT_MINOR: number;
+    /**
+     * @deprecated Consider using the SANEStatus enum directly.
+     *
+     * This object is not going away anytime soon (or ever probably).
+     *
+     * But you should consider using the equivalent enum because it doesn't
+     * require having a reference to the library module. All enums are
+     * exported with the package.
+     */
+    SANE_STATUS: SANEEnum<typeof SANEStatus, SANEStatus>;
+    /**
+     * @deprecated Consider using the SANEValueType enum directly.
+     *
+     * This object is not going away anytime soon (or ever probably).
+     *
+     * But you should consider using the equivalent enum because it doesn't
+     * require having a reference to the library module. All enums are
+     * exported with the package.
+     */
+    SANE_TYPE: SANEEnum<typeof SANEValueType, SANEValueType>;
+    /**
+     * @deprecated Consider using the SANEUnit enum directly.
+     *
+     * This object is not going away anytime soon (or ever probably).
+     *
+     * But you should consider using the equivalent enum because it doesn't
+     * require having a reference to the library module. All enums are
+     * exported with the package.
+     */
+    SANE_UNIT: SANEEnum<typeof SANEUnit, SANEUnit>;
+    /**
+     * @deprecated Consider using the SANEConstraintType enum directly.
+     *
+     * This object is not going away anytime soon (or ever probably).
+     *
+     * But you should consider using the equivalent enum because it doesn't
+     * require having a reference to the library module. All enums are
+     * exported with the package.
+     */
+    SANE_CONSTRAINT: SANEEnum<typeof SANEConstraintType, SANEConstraintType>;
+    /**
+     * @deprecated Consider using the SANEFrame enum directly.
+     *
+     * This object is not going away anytime soon (or ever probably).
+     *
+     * But you should consider using the equivalent enum because it doesn't
+     * require having a reference to the library module. All enums are
+     * exported with the package.
+     */
+    SANE_FRAME: SANEEnum<typeof SANEFrame, SANEFrame>;
+    /**
+     * Get the current state of the library.
+     *
+     * This is provided by sane-wasm, it's not part of SANE API.
+     */
+    sane_get_state: () => SANEState;
+    /**
+     * Equivalent to the SANE API C function `sane_init`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-init}
+     */
+    sane_init: () => {
+        status: SANEStatus.GOOD;
+        version_code: number;
+    } | {
+        status: Exclude<SANEStatus, SANEStatus.GOOD>;
+        version_code: null;
+    };
+    /**
+     * Equivalent to the SANE API C function `sane_exit`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-exit}
+     */
+    sane_exit: () => Promise<{
+        status: SANEStatus;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_get_devices`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-get-devices}
+     */
+    sane_get_devices: () => Promise<{
+        status: SANEStatus.GOOD;
+        devices: SANEDevice[];
+    } | {
+        status: Exclude<SANEStatus, SANEStatus.GOOD>;
+        devices: null;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_open`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-open}
+     */
+    sane_open: (devicename: string) => Promise<{
+        status: SANEStatus;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_close`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-close}
+     */
+    sane_close: () => Promise<{
+        status: SANEStatus;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_get_option_descriptor`.
+     *
+     * The result `option_descriptor` can be null even with
+     * `status = SANEStatus.GOOD`, it signals invalid option index.
+     *
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-get-option-descriptor}
+     */
+    sane_get_option_descriptor: (option: number) => {
+        status: SANEStatus;
+        option_descriptor: SANEOptionDescriptor | null;
+    };
+    /**
+     * Equivalent to the SANE API C function `sane_control_option`.
+     *
+     * With `a = SANE_ACTION_GET_VALUE` (get option value).
+     *
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-control-option}
+     */
+    sane_control_option_get_value: (option: number) => Promise<{
+        status: SANEStatus.GOOD;
+        value: any;
+    } | {
+        status: Exclude<SANEStatus, SANEStatus.GOOD>;
+        value: null;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_control_option`.
+     *
+     * With `a = SANE_ACTION_SET_VALUE` (set option value).
+     *
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-control-option}
+     */
+    sane_control_option_set_value: (option: number, value: any) => Promise<{
+        status: SANEStatus.GOOD;
+        info: SANEInfo;
+    } | {
+        status: Exclude<SANEStatus, SANEStatus.GOOD>;
+        info: null;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_control_option`.
+     *
+     * With `a = SANE_ACTION_SET_AUTO` (set option automatic).
+     *
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-control-option}
+     */
+    sane_control_option_set_auto: (option: number) => Promise<{
+        status: SANEStatus.GOOD;
+        info: SANEInfo;
+    } | {
+        status: Exclude<SANEStatus, SANEStatus.GOOD>;
+        info: null;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_get_parameters`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-get-parameters}
+     */
+    sane_get_parameters: () => {
+        status: SANEStatus.GOOD;
+        parameters: SANEParameters;
+    } | {
+        status: Exclude<SANEStatus, SANEStatus.GOOD>;
+        parameters: null;
+    };
+    /**
+     * Equivalent to the SANE API C function `sane_start`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-start}
+     */
+    sane_start: () => {
+        status: SANEStatus;
+    };
+    /**
+     * Equivalent to the SANE API C function `sane_read`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-read}
+     */
+    sane_read: () => Promise<{
+        status: SANEStatus.GOOD;
+        data: Uint8Array;
+    } | {
+        status: Exclude<SANEStatus, SANEStatus.GOOD>;
+        data: null;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_cancel`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-cancel}
+     */
+    sane_cancel: () => Promise<{
+        status: SANEStatus;
+    }>;
+    /**
+     * Equivalent to the SANE API C function `sane_strstatus`.
+     * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-strstatus}
+     */
+    sane_strstatus: (status: SANEStatus) => string;
+}
+/**
+ * SANE Emscripten module options (specific to sane-wasm).
+ */
+export type LibSANEOptions = {
+    /**
+     * Loader URL that serves the build artifacts (libsane.js etc.).
+     *
+     * The loader is only used on web environments.
+     *
+     * @defaultvalue "sane-wasm @ jsdelivr.net"
+     */
+    loaderURL?: string;
+    /**
+     * Should the loader prefetch the resources to a Bob object? This is
+     * required when loading from a different origin. Check the loader
+     * code for more information.
+     *
+     * The loader is only used on web environments.
+     *
+     * @defaultvalue `true`
+     */
+    loaderPrefetchToBlob?: boolean;
+    /**
+     * Should the loader remove the global module variable `window.LibSANE`?
+     *
+     * The loader is only used on web environments.
+     *
+     * @defaultvalue `true`
+     */
+    loaderRemoveGlobal?: boolean;
+    /**
+     * Enables SANE low-level debug messages, this can be quite verbose.
+     *
+     * @defaultvalue `false`
+     */
+    debugSANE?: boolean;
+    /**
+     * Enables libusb low-level debug messages, this can be quite verbose.
+     *
+     * @defaultvalue `false`
+     */
+    debugUSB?: boolean;
+    /**
+     * Enables debug messages for SANE function calls.
+     *
+     * @defaultvalue `false`
+     */
+    debugFunctionCalls?: boolean;
+    /**
+     * Sets the number of test devices for SANE's test backend.
+     *
+     * @defaultvalue `0`
+     */
+    debugTestDevices?: number;
+    /**
+     * Enables sane-wasm "promisify" to normalize the API. See pre.js for more
+     * information.
+     *
+     * @deprecated Setting this to `false` changes the API definition! Some
+     * functions may stop being asynchronous in some cases. You want this
+     * option enabled! This option may be removed in the future.
+     *
+     * @defaultvalue `true`
+     */
+    promisify?: boolean;
+    /**
+     * Enables sane-wasm "promisify" queue that queues function calls to
+     * prevent issues with calling multiple asynchronous functions. See pre.js
+     * for more information.
+     *
+     * @deprecated You want this option enabled! This option may be removed in
+     * the future.
+     *
+     * @defaultvalue `true`
+     */
+    promisifyQueue?: boolean;
+};
+/**
+ * The factory that initializes the core SANE Emscripten module.
+ */
+export type LibSANEFactory = (options?: {
+    /**
+     * Emscripten module options specific to sane-wasm.
+     */
+    sane?: LibSANEOptions;
+    /**
+     * Other Emscripten module options.
+     */
+    [k: string]: any;
+}) => Promise<LibSANE>;
+/**
+ * Main LibSANE factory.
+ */
+export declare const libsane: LibSANEFactory;
+/**
+ * @deprecated The default export may be removed in the future.
+ * Use the 'libsane' named export.
+ */
+export default libsane;

package/dist/index.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.libsane = exports.SANEFrame = exports.SANEConstraintType = exports.SANEUnit = exports.SANEValueType = exports.SANEStatus = void 0;
+/**
+ * Equivalent to the SANE API C enum `SANE_Status`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#status-type}
+ */
+var SANEStatus;
+(function (SANEStatus) {
+    SANEStatus[SANEStatus["GOOD"] = 0] = "GOOD";
+    SANEStatus[SANEStatus["UNSUPPORTED"] = 1] = "UNSUPPORTED";
+    SANEStatus[SANEStatus["CANCELLED"] = 2] = "CANCELLED";
+    SANEStatus[SANEStatus["DEVICE_BUSY"] = 3] = "DEVICE_BUSY";
+    SANEStatus[SANEStatus["INVAL"] = 4] = "INVAL";
+    SANEStatus[SANEStatus["EOF"] = 5] = "EOF";
+    SANEStatus[SANEStatus["JAMMED"] = 6] = "JAMMED";
+    SANEStatus[SANEStatus["NO_DOCS"] = 7] = "NO_DOCS";
+    SANEStatus[SANEStatus["COVER_OPEN"] = 8] = "COVER_OPEN";
+    SANEStatus[SANEStatus["IO_ERROR"] = 9] = "IO_ERROR";
+    SANEStatus[SANEStatus["NO_MEM"] = 10] = "NO_MEM";
+    SANEStatus[SANEStatus["ACCESS_DENIED"] = 11] = "ACCESS_DENIED";
+})(SANEStatus || (exports.SANEStatus = SANEStatus = {}));
+/**
+ * Equivalent to the SANE API C enum `SANE_Value_Type`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-value-type}
+ */
+var SANEValueType;
+(function (SANEValueType) {
+    SANEValueType[SANEValueType["BOOL"] = 0] = "BOOL";
+    SANEValueType[SANEValueType["INT"] = 1] = "INT";
+    SANEValueType[SANEValueType["FIXED"] = 2] = "FIXED";
+    SANEValueType[SANEValueType["STRING"] = 3] = "STRING";
+    SANEValueType[SANEValueType["BUTTON"] = 4] = "BUTTON";
+    SANEValueType[SANEValueType["GROUP"] = 5] = "GROUP";
+})(SANEValueType || (exports.SANEValueType = SANEValueType = {}));
+/**
+ * Equivalent to the SANE API C enum `SANE_Unit`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-value-unit}
+ */
+var SANEUnit;
+(function (SANEUnit) {
+    SANEUnit[SANEUnit["NONE"] = 0] = "NONE";
+    SANEUnit[SANEUnit["PIXEL"] = 1] = "PIXEL";
+    SANEUnit[SANEUnit["BIT"] = 2] = "BIT";
+    SANEUnit[SANEUnit["MM"] = 3] = "MM";
+    SANEUnit[SANEUnit["DPI"] = 4] = "DPI";
+    SANEUnit[SANEUnit["PERCENT"] = 5] = "PERCENT";
+    SANEUnit[SANEUnit["MICROSECOND"] = 6] = "MICROSECOND";
+})(SANEUnit || (exports.SANEUnit = SANEUnit = {}));
+/**
+ * Equivalent to the SANE API C enum `SANE_Constraint_Type`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#option-value-constraints}
+ */
+var SANEConstraintType;
+(function (SANEConstraintType) {
+    SANEConstraintType[SANEConstraintType["NONE"] = 0] = "NONE";
+    SANEConstraintType[SANEConstraintType["RANGE"] = 1] = "RANGE";
+    SANEConstraintType[SANEConstraintType["WORD_LIST"] = 2] = "WORD_LIST";
+    SANEConstraintType[SANEConstraintType["STRING_LIST"] = 3] = "STRING_LIST";
+})(SANEConstraintType || (exports.SANEConstraintType = SANEConstraintType = {}));
+/**
+ * Equivalent to the SANE API C enum `SANE_Frame`.
+ * @see {@link https://sane-project.gitlab.io/standard/1.06/api.html#sane-get-parameters}
+ */
+var SANEFrame;
+(function (SANEFrame) {
+    SANEFrame[SANEFrame["GRAY"] = 0] = "GRAY";
+    SANEFrame[SANEFrame["RGB"] = 1] = "RGB";
+    SANEFrame[SANEFrame["RED"] = 2] = "RED";
+    SANEFrame[SANEFrame["GREEN"] = 3] = "GREEN";
+    SANEFrame[SANEFrame["BLUE"] = 4] = "BLUE";
+})(SANEFrame || (exports.SANEFrame = SANEFrame = {}));
+/**
+ * Main LibSANE factory.
+ */
+exports.libsane = require('../lib');
+/**
+ * @deprecated The default export may be removed in the future.
+ * Use the 'libsane' named export.
+ */
+exports.default = exports.libsane;

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "sane-wasm",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "A project to bring the SANE API to the web.",
-  "main": "lib/index.js",
-  "types": "libsane.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "scripts": {
     "test": "jest",
-    "clean": "./build.sh --with-docker --no-build --clean",
-    "build": "./build.sh --with-docker --clean",
-    "build-debug": "./build.sh --with-docker --debug --emrun"
+    "clean": "npm run clean:ts && npm run clean:sane",
+    "clean:ts": "rm -rf dist/ docs/",
+    "clean:sane": "./build.sh --no-build --clean",
+    "prebuild": "rm -rf dist/ docs/ build/",
+    "build": "npm run build:ts && npm run build:sane",
+    "build:ts": "tsc && typedoc",
+    "postbuild:ts": "rm -rf dist/docs-plugin.*",
+    "build:sane": "./build.sh --with-docker --clean",
+    "debug:sane": "./build.sh --with-docker --debug --emrun"
   },
   "files": [
+    "dist/",
     "lib/",
     "build/",
     "libsane.d.ts",
@@ -32,11 +39,18 @@
       "jest-extended/all"
     ]
   },
-  "dependencies": {
+  "peerDependencies": {
     "usb": "^2.10.0"
   },
+  "peerDependenciesMeta": {
+    "usb": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "jest": "^29.6.4",
-    "jest-extended": "^4.0.1"
+    "jest-extended": "^4.0.1",
+    "typedoc": "^0.25.0",
+    "typescript": "^5.2.2"
   }
 }

package/libsane.d.ts

@@ -1,163 +0,0 @@
-export enum SANEStatus {
-    GOOD = 0,
-    UNSUPPORTED,
-    CANCELLED,
-    DEVICE_BUSY,
-    INVAL,
-    EOF,
-    JAMMED,
-    NO_DOCS,
-    COVER_OPEN,
-    IO_ERROR,
-    NO_MEM,
-    ACCESS_DENIED,
-}
-
-export enum SANEValueType {
-    BOOL = 0,
-    INT,
-    FIXED,
-    STRING,
-    BUTTON,
-    GROUP,
-}
-
-export enum SANEUnit {
-    NONE = 0,
-    PIXEL,
-    BIT,
-    MM,
-    DPI,
-    PERCENT,
-    MICROSECOND,
-}
-
-export enum SANEConstraintType {
-    NONE = 0,
-    RANGE,
-    WORD_LIST,
-    STRING_LIST,
-}
-
-export enum SANEFrame {
-    GRAY = 0,
-    RGB,
-    RED,
-    GREEN,
-    BLUE,
-}
-
-export type SANEState = {
-    initialized: boolean;
-    version_code: number;
-    version: {
-        major: number;
-        minor: number;
-        build: number;
-    },
-    open: boolean;
-}
-
-export type SANEDevice = {
-    name: string;
-    vendor: string;
-    model: string;
-    type: string;
-}
-
-export type SANEOptionDescriptor = {
-    name: string;
-    title: string;
-    desc: string;
-    type: SANEValueType;
-    unit: SANEUnit;
-    size: number;
-    cap: {
-        SOFT_SELECT: boolean;
-        HARD_SELECT: boolean;
-        SOFT_DETECT: boolean;
-        EMULATED: boolean;
-        AUTOMATIC: boolean;
-        INACTIVE: boolean;
-        ADVANCED: boolean;
-    };
-} & ({
-    constraint_type: SANEConstraintType.NONE
-    constraint: null
-} | {
-    constraint_type: SANEConstraintType.RANGE
-    constraint: {
-        min: number;
-        max: number;
-        quant: number;
-    }
-} | {
-    constraint_type: SANEConstraintType.WORD_LIST
-    constraint: number[]
-} | {
-    constraint_type: SANEConstraintType.STRING_LIST
-    constraint: string[]
-})
-
-export type SANEInfo = {
-    INEXACT: boolean;
-    RELOAD_OPTIONS: boolean;
-    RELOAD_PARAMS: boolean;
-}
-
-export type SANEParameters = {
-    format: SANEFrame;
-    last_frame: boolean;
-    bytes_per_line: number;
-    pixels_per_line: number;
-    lines: number;
-    depth: number;
-}
-
-type SANEEnum<E, TE> = E & {
-    asString: (value: TE) => string;
-}
-
-export interface LibSANE {
-    SANE_WASM_COMMIT: string;
-    SANE_WASM_VERSION: string;
-    SANE_WASM_BACKENDS: string;
-
-    SANE_CURRENT_MAJOR: number;
-    SANE_CURRENT_MINOR: number;
-
-    SANE_STATUS: SANEEnum<typeof SANEStatus, SANEStatus>;
-    SANE_TYPE: SANEEnum<typeof SANEValueType, SANEValueType>;
-    SANE_UNIT: SANEEnum<typeof SANEUnit, SANEUnit>;
-    SANE_CONSTRAINT: SANEEnum<typeof SANEConstraintType, SANEConstraintType>;
-    SANE_FRAME: SANEEnum<typeof SANEFrame, SANEFrame>;
-
-    sane_get_state: () => SANEState;
-    sane_init: () => { status: SANEStatus; version_code: number };
-    sane_exit: () => Promise<{ status: SANEStatus; }>;
-    sane_get_devices: () => Promise<{ status: SANEStatus; devices: SANEDevice[] }>;
-    sane_open: (devicename: string) => Promise<{ status: SANEStatus; }>;
-    sane_close: () => Promise<{ status: SANEStatus; }>;
-    sane_get_option_descriptor: (option: number) => { status: SANEStatus; option_descriptor: SANEOptionDescriptor | null };
-    sane_control_option_get_value: (option: number) => Promise<{ status: SANEStatus; value: any }>;
-    sane_control_option_set_value: (option: number, value: any) => Promise<{ status: SANEStatus; info: SANEInfo }>;
-    sane_control_option_set_auto: (option: number) => Promise<{ status: SANEStatus; info: SANEInfo }>;
-    sane_get_parameters: () => { status: SANEStatus; parameters: SANEParameters };
-    sane_start: () => { status: SANEStatus; };
-    sane_read: () => Promise<{ status: SANEStatus; data: Uint8Array }>;
-    sane_cancel: () => Promise<{ status: SANEStatus; }>;
-    sane_strstatus: (status: SANEStatus) => string;
-}
-
-export type LibSANEFactory = (option?: {
-    sane?: {
-        debugSANE?: boolean;
-        debugUSB?: boolean;
-        debugFunctionCalls?: boolean;
-        debugTestDevices?: number;
-        promisify?: boolean;
-        promisifyQueue?: boolean;
-    }
-} & {
-    [k: string]: any
-}) => Promise<LibSANE>