@munchi_oy/react-native-epson-printer 1.0.6 → 1.0.8

package/README.md

@@ -30,6 +30,25 @@ This package provides:
 
 This package does not include Star or Sunmi drivers.
 
+## Runtime Contract
+
+For both iOS and Android, the SDK aims to provide this behavior:
+
+- Native printer work may take time, especially for Bluetooth connection, status checks, and image printing.
+- Slow printer operations are acceptable; visible app hangs are not.
+- Printer work must not block the app UI/main thread while running.
+- Errors from native printer operations must reject back to JS and must not be swallowed.
+- Image and logo printing may be more expensive than text-only receipts, but must still remain asynchronous from the app's point of view.
+
+## Observed Performance Expectations
+
+These are real-device expectations, not strict guarantees:
+
+- iOS: around 3s end-to-end can be acceptable if the app UI remains responsive.
+- Android: the first print may take around 5-6s, with later warm prints often dropping to around 2-3s.
+- Actual timing depends on connection state, Bluetooth behavior, printer readiness, and whether the receipt includes images.
+- Responsiveness and correct JS error propagation matter more than raw duration.
+
 ## Behavior Support (implemented)
 
 | Behavior | Status | Details |
@@ -41,6 +60,7 @@ This package does not include Star or Sunmi drivers.
 | Retry for transient busy/timeout states | Implemented | Native operations retry for retryable states (`BUSY`, `IN_USE`, timeout-family errors). |
 | Print receive timeout guard | Implemented | Native print call fails with `PRINT_TIMEOUT` if printer callback does not return within 30s. |
 | iOS stale-session recovery | Implemented | One-shot session recovery + reconnect + retry for stale/busy/offline connection scenarios. |
+| Non-blocking native printer execution | Implemented | Native connect / print / status work is executed off the app UI thread on both iOS and Android. |
 | Post-print auto-disconnect | Implemented | JS driver schedules disconnect after 5s idle after print completion. |
 | Android warm reconnect cache | Implemented | Native Android keeps a short-lived connection cache (up to 120s) for faster reconnect. |
 | Discovery cleanup/filtering | Implemented | Duplicate targets are deduped and Epson sub-devices such as `[local_display]` are filtered out. |
@@ -194,6 +214,13 @@ await printer.printEmbedded({
 });
 ```
 
+### Image printing expectations
+
+- Image printing is supported.
+- Image printing can take longer than text-only receipts because the image may need decode, resize, rasterization, and transport work.
+- This extra work should not block the app UI.
+- If image printing fails, the error should still reject back to JS like any other print failure.
+
 ### Cash drawer
 
 ```ts

package/android/src/main/java/com/munchiepsonprinter/MunchiEpsonModule.java

@@ -44,6 +44,13 @@ import java.util.IdentityHashMap;
 import java.util.Map;
 import java.util.Set;
 import java.util.UUID;
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 
 public class MunchiEpsonModule extends ReactContextBaseJavaModule implements ConnectionListener, StatusChangeListener, ReceiveListener, DiscoveryListener {
     private static final String MODULE_NAME = "MunchiEpsonModule";
@@ -52,12 +59,19 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
     private static final String EVENT_PRINTER_RECEIVE = "onPrinterReceive";
 
     private static final int DEFAULT_DISCOVERY_TIMEOUT_MS = 5000;
+    private static final int DEFAULT_CONNECT_TIMEOUT_MS = 5000;
     private static final int PRINT_TIMEOUT_MS = 30000;
     private static final int CONNECTION_CACHE_TTL_MS = 120000;
+    private static final int STATUS_OPERATION_TIMEOUT_MS = 3000;
+    private static final int CACHE_HEALTH_CHECK_TIMEOUT_MS = 800;
+    private static final int SEND_OPERATION_TIMEOUT_MS = 5000;
+    private static final String RECONNECT_REQUIRED_CODE = "PRINTER_RECONNECT_REQUIRED";
+    private static final String RECONNECT_REQUIRED_MESSAGE = "Printer connection was lost. Reconnect the printer in Android Bluetooth settings, then try again.";
 
     private final ReactApplicationContext reactContext;
     private final Handler mainHandler = new Handler(Looper.getMainLooper());
     private final Object lock = new Object();
+    private final ExecutorService printerExecutor = Executors.newCachedThreadPool();
 
     private final Map<String, EpsonSession> sessions = new HashMap<>();
     private final Map<Printer, String> printerToSessionId = new IdentityHashMap<>();
@@ -167,6 +181,7 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
     public void connect(String sessionId, String target, double timeout, double model, double lang, Promise promise) {
         int safeModel = normalizeModel((int) model);
         int safeLang = normalizeLanguage((int) lang);
+        int safeTimeout = normalizeConnectTimeout((int) timeout);
 
         EpsonSession session;
         EpsonSession ownerSessionToReclaim = null;
@@ -210,69 +225,67 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
 
         teardownPrinter(session, true);
 
-        Printer printer = null;
-        if (cachedConnection != null) {
-            if (cachedConnection.model == safeModel
-                && cachedConnection.lang == safeLang
-                && isConnectionHealthy(cachedConnection.printer)) {
-                printer = cachedConnection.printer;
-            } else {
-                disconnectPrinterQuietly(cachedConnection.printer);
-            }
-        }
+        printerExecutor.execute(() -> {
+            Printer printer = null;
 
-        if (printer != null) {
-            synchronized (lock) {
-                EpsonSession latestSession = sessions.get(sessionId);
-                if (latestSession == null) {
-                    disconnectPrinterQuietly(printer);
-                    promise.reject("SESSION_ERROR", "Session disposed while connecting");
-                    return;
+            try {
+                if (cachedConnection != null) {
+                    if (cachedConnection.model == safeModel && cachedConnection.lang == safeLang) {
+                        if (isBluetoothTarget(target)) {
+                            disconnectPrinterQuietly(cachedConnection.printer);
+                        } else if (isConnectionHealthy(cachedConnection.printer, CACHE_HEALTH_CHECK_TIMEOUT_MS)) {
+                            printer = cachedConnection.printer;
+                        } else {
+                            disconnectPrinterQuietly(cachedConnection.printer);
+                        }
+                    } else {
+                        disconnectPrinterQuietly(cachedConnection.printer);
+                    }
                 }
 
-                latestSession.printer = printer;
-                latestSession.target = target;
-                latestSession.model = safeModel;
-                latestSession.lang = safeLang;
-                printerToSessionId.put(printer, sessionId);
-                targetToSessionId.put(target, sessionId);
-            }
-            promise.resolve(null);
-            return;
-        }
+                if (printer == null) {
+                    Printer freshPrinter = new Printer(safeModel, safeLang, reactContext.getApplicationContext());
+                    printer = freshPrinter;
+                    freshPrinter.setConnectionEventListener(this);
+                    freshPrinter.setStatusChangeEventListener(this);
+                    freshPrinter.setReceiveEventListener(this);
+                    runPrinterCall(() -> {
+                        freshPrinter.connect(target, safeTimeout);
+                        return null;
+                    }, safeTimeout);
+                    freshPrinter.startMonitor();
+                }
 
-        try {
-            printer = new Printer(safeModel, safeLang, reactContext.getApplicationContext());
-            printer.setConnectionEventListener(this);
-            printer.setStatusChangeEventListener(this);
-            printer.setReceiveEventListener(this);
-            printer.connect(target, (int) timeout);
-            printer.startMonitor();
-        } catch (Exception error) {
-            if (printer != null) {
-                disconnectPrinterQuietly(printer);
-            }
-            rejectWithEposError(promise, "CONNECT_ERROR", "Failed to connect", error);
-            return;
-        }
+                synchronized (lock) {
+                    EpsonSession latestSession = sessions.get(sessionId);
+                    if (latestSession == null) {
+                        disconnectPrinterQuietly(printer);
+                        promise.reject("SESSION_ERROR", "Session disposed while connecting");
+                        return;
+                    }
 
-        synchronized (lock) {
-            EpsonSession latestSession = sessions.get(sessionId);
-            if (latestSession == null) {
-                disconnectPrinterQuietly(printer);
-                promise.reject("SESSION_ERROR", "Session disposed while connecting");
-                return;
-            }
+                    latestSession.printer = printer;
+                    latestSession.target = target;
+                    latestSession.model = safeModel;
+                    latestSession.lang = safeLang;
+                    printerToSessionId.put(printer, sessionId);
+                    targetToSessionId.put(target, sessionId);
+                }
 
-            latestSession.printer = printer;
-            latestSession.target = target;
-            latestSession.model = safeModel;
-            latestSession.lang = safeLang;
-            printerToSessionId.put(printer, sessionId);
-            targetToSessionId.put(target, sessionId);
-        }
+                promise.resolve(null);
+            } catch (Exception error) {
+                if (printer != null) {
+                    disconnectPrinterQuietly(printer);
+                }
 
-        promise.resolve(null);
+                if (requiresReconnectInstruction(target, error)) {
+                    promise.reject(RECONNECT_REQUIRED_CODE, RECONNECT_REQUIRED_MESSAGE);
+                    return;
+                }
+
+                rejectWithEposError(promise, "CONNECT_ERROR", "Failed to connect", error);
+            }
+        });
     }
 
     @ReactMethod
@@ -295,6 +308,7 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
     public void print(String sessionId, ReadableArray commands, Promise promise) {
         EpsonSession session;
         Printer printer;
+        String target;
         synchronized (lock) {
             session = sessions.get(sessionId);
             if (session == null || session.printer == null) {
@@ -306,65 +320,80 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
                 return;
             }
             printer = session.printer;
+            target = session.target;
         }
 
-        if (!ensureBluetoothOperationReadiness(session.target, promise)) {
-            return;
-        }
-
-        PrinterStatusInfo status;
-        try {
-            status = printer.getStatus();
-        } catch (Exception error) {
-            detachUnhealthyPrinter(sessionId, printer);
-            rejectWithEposError(promise, "PRINT_ERROR", "Printer is not reachable", error);
-            return;
-        }
-
-        if (!isStatusReady(status)) {
-            detachUnhealthyPrinter(sessionId, printer);
-            promise.reject("PRINTER_OFFLINE", "Printer is offline or unreachable");
+        if (!ensureBluetoothOperationReadiness(target, promise)) {
             return;
         }
 
-        try {
-            printer.clearCommandBuffer();
-            applyCommands(printer, commands);
-        } catch (Exception error) {
-            rejectWithEposError(promise, "PRINT_ERROR", "Failed to build print data", error);
-            return;
-        }
+        printerExecutor.execute(() -> {
+            try {
+                PrinterStatusInfo status = runPrinterCall(printer::getStatus, STATUS_OPERATION_TIMEOUT_MS);
+                if (!isStatusReady(status)) {
+                    detachUnhealthyPrinter(sessionId, printer);
+                    promise.reject("PRINTER_OFFLINE", "Printer is offline or unreachable");
+                    return;
+                }
 
-        synchronized (lock) {
-            session.printPromise = promise;
-            Runnable timeoutRunnable = () -> handlePrintTimeout(sessionId);
-            session.printTimeoutRunnable = timeoutRunnable;
-            mainHandler.postDelayed(timeoutRunnable, PRINT_TIMEOUT_MS);
-        }
+                printer.clearCommandBuffer();
+                applyCommands(printer, commands);
+            } catch (Exception error) {
+                detachUnhealthyPrinter(sessionId, printer);
+                if (requiresReconnectInstruction(target, error)) {
+                    promise.reject(RECONNECT_REQUIRED_CODE, RECONNECT_REQUIRED_MESSAGE);
+                } else if (error instanceof Epos2Exception) {
+                    rejectWithEposError(promise, "PRINT_ERROR", "Printer is not reachable", error);
+                } else {
+                    rejectWithEposError(promise, "PRINT_ERROR", "Failed to build print data", error);
+                }
+                return;
+            }
 
-        try {
-            printer.sendData(Printer.PARAM_DEFAULT);
-        } catch (Exception error) {
-            detachUnhealthyPrinter(sessionId, printer);
-            Promise pending = null;
             synchronized (lock) {
                 EpsonSession latestSession = sessions.get(sessionId);
-                if (latestSession != null) {
-                    pending = latestSession.printPromise;
-                    cancelPrintTimeoutLocked(latestSession);
-                    latestSession.printPromise = null;
-                    latestSession.printTimeoutRunnable = null;
+                if (latestSession == null || latestSession.printer != printer) {
+                    promise.reject("PRINT_ERROR", "Printer not connected");
+                    return;
                 }
+                latestSession.printPromise = promise;
+                Runnable timeoutRunnable = () -> handlePrintTimeout(sessionId);
+                latestSession.printTimeoutRunnable = timeoutRunnable;
+                mainHandler.postDelayed(timeoutRunnable, PRINT_TIMEOUT_MS);
             }
-            if (pending != null) {
-                rejectWithEposError(pending, "PRINT_ERROR", "Failed to send data", error);
+
+            try {
+                runPrinterCall(() -> {
+                    printer.sendData(Printer.PARAM_DEFAULT);
+                    return null;
+                }, SEND_OPERATION_TIMEOUT_MS);
+            } catch (Exception error) {
+                detachUnhealthyPrinter(sessionId, printer);
+                Promise pending = null;
+                synchronized (lock) {
+                    EpsonSession latestSession = sessions.get(sessionId);
+                    if (latestSession != null) {
+                        pending = latestSession.printPromise;
+                        cancelPrintTimeoutLocked(latestSession);
+                        latestSession.printPromise = null;
+                        latestSession.printTimeoutRunnable = null;
+                    }
+                }
+                if (pending != null) {
+                    if (requiresReconnectInstruction(target, error)) {
+                        pending.reject(RECONNECT_REQUIRED_CODE, RECONNECT_REQUIRED_MESSAGE);
+                    } else {
+                        rejectWithEposError(pending, "PRINT_ERROR", "Failed to send data", error);
+                    }
+                }
             }
-        }
+        });
     }
 
     @ReactMethod
     public void getStatus(String sessionId, Promise promise) {
         EpsonSession session;
+        Printer printer;
         synchronized (lock) {
             session = sessions.get(sessionId);
         }
@@ -374,30 +403,39 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
             return;
         }
 
+        printer = session.printer;
+
         if (!ensureBluetoothOperationReadiness(session.target, promise)) {
             return;
         }
 
-        try {
-            PrinterStatusInfo status = session.printer.getStatus();
-            if (status == null) {
-                promise.reject("STATUS_ERROR", "Failed to retrieve status");
-                return;
-            }
-
-            WritableMap statusMap = Arguments.createMap();
-            boolean paperEmpty = status.getPaper() == Printer.PAPER_EMPTY;
-            statusMap.putBoolean("online", isStatusReady(status));
-            statusMap.putBoolean("coverOpen", status.getCoverOpen() == Printer.TRUE);
-            statusMap.putBoolean("paperEmpty", paperEmpty);
-            statusMap.putString("paper", mapPaperStatus(status.getPaper()));
-            statusMap.putBoolean("drawerOpen", status.getDrawer() == Printer.DRAWER_HIGH);
-            statusMap.putString("errorStatus", mapErrorStatus(status.getErrorStatus()));
+        printerExecutor.execute(() -> {
+            try {
+                PrinterStatusInfo status = runPrinterCall(printer::getStatus, STATUS_OPERATION_TIMEOUT_MS);
+                if (status == null) {
+                    promise.reject("STATUS_ERROR", "Failed to retrieve status");
+                    return;
+                }
 
-            promise.resolve(statusMap);
-        } catch (Exception error) {
-            rejectWithEposError(promise, "STATUS_ERROR", "Failed to retrieve status", error);
-        }
+                WritableMap statusMap = Arguments.createMap();
+                boolean paperEmpty = status.getPaper() == Printer.PAPER_EMPTY;
+                statusMap.putBoolean("online", isStatusReady(status));
+                statusMap.putBoolean("coverOpen", status.getCoverOpen() == Printer.TRUE);
+                statusMap.putBoolean("paperEmpty", paperEmpty);
+                statusMap.putString("paper", mapPaperStatus(status.getPaper()));
+                statusMap.putBoolean("drawerOpen", status.getDrawer() == Printer.DRAWER_HIGH);
+                statusMap.putString("errorStatus", mapErrorStatus(status.getErrorStatus()));
+
+                promise.resolve(statusMap);
+            } catch (Exception error) {
+                detachUnhealthyPrinter(sessionId, printer);
+                if (requiresReconnectInstruction(session.target, error)) {
+                    promise.reject(RECONNECT_REQUIRED_CODE, RECONNECT_REQUIRED_MESSAGE);
+                    return;
+                }
+                rejectWithEposError(promise, "STATUS_ERROR", "Failed to retrieve status", error);
+            }
+        });
     }
 
     @Override
@@ -534,6 +572,8 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
             clearDiscoveryStateLocked();
         }
 
+        printerExecutor.shutdownNow();
+
         super.invalidate();
     }
 
@@ -624,6 +664,10 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
         }
 
         if (disconnect && target != null && model >= 0 && lang >= 0) {
+            if (isBluetoothTarget(target)) {
+                disconnectPrinterQuietly(printer);
+                return;
+            }
             synchronized (lock) {
                 if (!targetToSessionId.containsKey(target)) {
                     cacheConnectionLocked(target, model, lang, printer);
@@ -676,9 +720,9 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
         cachedConnections.clear();
     }
 
-    private boolean isConnectionHealthy(Printer printer) {
+    private boolean isConnectionHealthy(Printer printer, int timeoutMs) {
         try {
-            PrinterStatusInfo status = printer.getStatus();
+            PrinterStatusInfo status = runPrinterCall(printer::getStatus, timeoutMs);
             return isStatusReady(status);
         } catch (Exception ignored) {
             return false;
@@ -1072,6 +1116,58 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
             || locationManager.isProviderEnabled(LocationManager.NETWORK_PROVIDER);
     }
 
+    private int normalizeConnectTimeout(int timeout) {
+        if (timeout <= 0) {
+            return DEFAULT_CONNECT_TIMEOUT_MS;
+        }
+        return timeout;
+    }
+
+    private boolean requiresReconnectInstruction(String target, Exception error) {
+        if (!isBluetoothTarget(target)) {
+            return false;
+        }
+
+        if (error instanceof PrinterOperationTimeoutException) {
+            return true;
+        }
+
+        if (error instanceof Epos2Exception) {
+            int status = ((Epos2Exception) error).getErrorStatus();
+            return status == Epos2Exception.ERR_CONNECT
+                || status == Epos2Exception.ERR_TIMEOUT
+                || status == Epos2Exception.ERR_DISCONNECT
+                || status == Epos2Exception.ERR_PROCESSING
+                || status == Epos2Exception.ERR_FAILURE
+                || status == Epos2Exception.ERR_ILLEGAL;
+        }
+
+        String message = String.valueOf(error.getMessage()).toUpperCase();
+        return message.contains("DISCONNECT")
+            || message.contains("OFFLINE")
+            || message.contains("NOT CONNECTED");
+    }
+
+    private <T> T runPrinterCall(Callable<T> callable, int timeoutMs) throws Exception {
+        Future<T> future = printerExecutor.submit(callable);
+        try {
+            return future.get(timeoutMs, TimeUnit.MILLISECONDS);
+        } catch (TimeoutException error) {
+            future.cancel(true);
+            throw new PrinterOperationTimeoutException(timeoutMs, error);
+        } catch (InterruptedException error) {
+            future.cancel(true);
+            Thread.currentThread().interrupt();
+            throw error;
+        } catch (ExecutionException error) {
+            Throwable cause = error.getCause();
+            if (cause instanceof Exception) {
+                throw (Exception) cause;
+            }
+            throw new Exception(cause);
+        }
+    }
+
     private int normalizeLanguage(int lang) {
         if (lang >= 0 && lang <= 7) {
             return lang;
@@ -1226,4 +1322,10 @@ public class MunchiEpsonModule extends ReactContextBaseJavaModule implements Con
             this.printer = printer;
         }
     }
+
+    private static final class PrinterOperationTimeoutException extends Exception {
+        PrinterOperationTimeoutException(int timeoutMs, Throwable cause) {
+            super("Printer operation timed out after " + timeoutMs + "ms", cause);
+        }
+    }
 }

package/dist/errors.d.ts

@@ -7,6 +7,7 @@ export declare enum PrinterErrorCode {
     UNKNOWN = "UNKNOWN"
 }
 export declare enum PrinterTranslationCode {
+    ERR_PRINTER_RECONNECT_REQUIRED = "printer.error.reconnect_required",
     ERR_PRINTER_OFFLINE = "printer.error.offline",
     ERR_PRINTER_BUSY = "printer.error.busy",
     ERR_PRINTER_COVER_OPEN = "printer.error.cover_open",

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oBAAY,gBAAgB;IAC1B,iBAAiB,sBAAsB;IACvC,YAAY,iBAAiB;IAC7B,gBAAgB,qBAAqB;IACrC,OAAO,YAAY;IACnB,qBAAqB,0BAA0B;IAC/C,OAAO,YAAY;CACpB;AAED,oBAAY,sBAAsB;IAChC,mBAAmB,0BAA0B;IAC7C,gBAAgB,uBAAuB;IACvC,sBAAsB,6BAA6B;IACnD,uBAAuB,8BAA8B;IACrD,sBAAsB,qCAAqC;IAC3D,WAAW,0BAA0B;CACtC;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAElC,IAAI,EAAE,gBAAgB;IACtB,eAAe,EAAE,sBAAsB;IAEvC,aAAa,CAAC,EAAE,OAAO;gBAHvB,IAAI,EAAE,gBAAgB,EACtB,eAAe,EAAE,sBAAsB,EAC9C,OAAO,EAAE,MAAM,EACR,aAAa,CAAC,EAAE,OAAO,YAAA;CAQjC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oBAAY,gBAAgB;IAC1B,iBAAiB,sBAAsB;IACvC,YAAY,iBAAiB;IAC7B,gBAAgB,qBAAqB;IACrC,OAAO,YAAY;IACnB,qBAAqB,0BAA0B;IAC/C,OAAO,YAAY;CACpB;AAED,oBAAY,sBAAsB;IAChC,8BAA8B,qCAAqC;IACnE,mBAAmB,0BAA0B;IAC7C,gBAAgB,uBAAuB;IACvC,sBAAsB,6BAA6B;IACnD,uBAAuB,8BAA8B;IACrD,sBAAsB,qCAAqC;IAC3D,WAAW,0BAA0B;CACtC;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAElC,IAAI,EAAE,gBAAgB;IACtB,eAAe,EAAE,sBAAsB;IAEvC,aAAa,CAAC,EAAE,OAAO;gBAHvB,IAAI,EAAE,gBAAgB,EACtB,eAAe,EAAE,sBAAsB,EAC9C,OAAO,EAAE,MAAM,EACR,aAAa,CAAC,EAAE,OAAO,YAAA;CAQjC"}