fix(utils): add global debug mode

docs/getting-started.md

@@ -8,7 +8,7 @@ If your application setup uses a bundler (like [Vite](https://vitejs.dev/)), jus
 npm i hybrids
 ```
 
-Otherwise, you can use it directly from a number of CDNs, which provide a hybrids from the registry:
+Otherwise, you can use it directly from a number of CDNs, which provide hybrids from the registry:
 
 * [https://esm.sh/hybrids@^9](https://esm.sh/hybrids@^9) (2 requests, minified)
 * [https://cdn.skypack.dev/hybrids@^9?min](https://cdn.skypack.dev/hybrids@^9?min) (2 request, minified)
@@ -40,3 +40,14 @@ If the entry point imports files that do not support HMR, you can place the abov
 ## Browser Support
 
 The library source code uses ES modules and currently supported JavaScript syntax by all of the major browsers. You can use hybrids in all modern browsers without code transpilation and bundling.
+
+## Debug Mode
+
+The library provides the debug mode used by some of the modules. Usually, it enables additional logging and error messages. To enable it, run `debug()` function before any other code. It is advised to protect the debug mode from the production environment by running it conditionally (according to your application setup)
+
+```javascript
+import { debug } from 'hybrids';
+
+// The condition might differ according to your setup
+if (import.meta.env.DEV) debug();
+```

docs/router/usage.md

@@ -323,20 +323,6 @@ In the above example, for both `OneView` and `TwoView` the `<my-link>` will be a
 
 ## Debug Mode
 
-```typescript
-router.debug(flag = true): void
-```
-
-* **arguments**:
-  * `flag` - a boolean flag, defaults to `true`
-
-The router provides a global debug mode, which logs the navigation events. It simplifies access to the current view in the DevTools console by the `$$0` reference (similar to the last selected element in the Elements panel).
+The router in debug mode logs the navigation events. Also, it simplifies access to the current view in the DevTools console by the `$$0` reference (similar to the last selected element in the Elements panel). 
 
-It is advised to protect the router debug mode from the production environment by running it conditionally (according to your application setup):
-
-```javascript
-import { router } from "hybrids";
-
-// The condition might differ according to your setup
-if (import.meta.env.DEV) router.debug();
-```
+You can find more information about the debug mode in the [Debug Mode](/getting-started.md#debug-mode) section of the documentation.

docs/store/usage.md

@@ -573,3 +573,9 @@ define({
 ```
 
 The Error instance is not required, but it can be helpful to display the general error message.
+
+## Debug Mode
+
+The store in the debug mode logs error messages when storage `set()` or `get()` methods throw an error.
+
+You can find more information about the debug mode in the [Debug Mode](/getting-started.md#debug-mode) section of the documentation.

src/index.js

@@ -10,4 +10,4 @@ export { localize, msg } from "./localize.js";
 
 export { html, svg } from "./template/index.js";
 
-export { dispatch } from "./utils.js";
+export { dispatch, debug } from "./utils.js";

src/router.js

@@ -1,5 +1,5 @@
 import * as cache from "./cache.js";
-import { deferred, dispatch, walkInShadow } from "./utils.js";
+import { deferred, dispatch, walkInShadow, debug } from "./utils.js";
 import { constructors } from "./define.js";
 
 const connect = Symbol("router.connect");
@@ -12,11 +12,6 @@ const routers = new WeakMap();
 let rootRouter = null;
 const entryPoints = new Set();
 
-let debug = false;
-function setDebug(value = true) {
-  debug = !!value;
-}
-
 const scrollMap = new WeakMap();
 const focusMap = new WeakMap();
 function saveLayout() {
@@ -1184,7 +1179,7 @@ function router(views, options) {
 export default Object.freeze(
   Object.assign(router, {
     connect,
-    debug: setDebug,
+    debug,
     url: getUrl,
     backUrl: getBackUrl,
     guardUrl: getGuardUrl,

src/store.js

@@ -1,5 +1,5 @@
 import * as cache from "./cache.js";
-import { storePointer, deferred } from "./utils.js";
+import { storePointer, deferred, isDebugMode } from "./utils.js";
 
 const connect = Symbol("store.connect");
 
@@ -1033,8 +1033,8 @@ function notFoundError(Model, stringId) {
   return err;
 }
 
-function mapError(model, err, suppressLog) {
-  if (suppressLog !== false && !notFoundErrors.has(err)) {
+function mapError(model, err) {
+  if (isDebugMode() && !notFoundErrors.has(err)) {
     console.error(err);
   }
 
@@ -1362,7 +1362,6 @@ function set(model, values = {}) {
           mapError(
             config.placeholder(resultId),
             notFoundError(config.model, id),
-            false,
           ),
         true,
       );
@@ -1417,7 +1416,7 @@ function sync(model, values) {
     config,
     id,
     resultModel ||
-      mapError(config.placeholder(id), notFoundError(config.model, id), false),
+      mapError(config.placeholder(id), notFoundError(config.model, id)),
   );
 }
 

src/utils.js

@@ -43,5 +43,14 @@ export function walkInShadow(target, cb) {
   }
 }
 
+let debugMode = false;
+export function debug() {
+  debugMode = true;
+}
+
+export function isDebugMode() {
+  return debugMode;
+}
+
 export const deferred = Promise.resolve();
 export const storePointer = new WeakMap();

types/index.d.ts

@@ -414,6 +414,8 @@ export function dispatch(
   options?: CustomEventInit,
 ): boolean;
 
+export function debug(): void;
+
 /* Template Engine */
 
 export interface UpdateFunctionWithMethods<E> extends UpdateFunction<E> {