diff --git a/docs/getting-started.md b/docs/getting-started.md index 9e84fe42..c6937c1a 100644 --- a/docs/getting-started.md +++ b/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(); +``` diff --git a/docs/router/usage.md b/docs/router/usage.md index 7d2f402b..3d6e012a 100644 --- a/docs/router/usage.md +++ b/docs/router/usage.md @@ -323,20 +323,6 @@ In the above example, for both `OneView` and `TwoView` the `` 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. diff --git a/docs/store/usage.md b/docs/store/usage.md index 2b85a75a..6f18da89 100644 --- a/docs/store/usage.md +++ b/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. diff --git a/src/index.js b/src/index.js index 3cd63aaa..d29371b2 100644 --- a/src/index.js +++ b/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"; diff --git a/src/router.js b/src/router.js index eda68e08..bcb9f249 100644 --- a/src/router.js +++ b/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, diff --git a/src/store.js b/src/store.js index 1c9857ed..282d9127 100644 --- a/src/store.js +++ b/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)), ); } diff --git a/src/utils.js b/src/utils.js index f01e25ee..09bd604d 100644 --- a/src/utils.js +++ b/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(); diff --git a/types/index.d.ts b/types/index.d.ts index fc452b4e..1faba964 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -414,6 +414,8 @@ export function dispatch( options?: CustomEventInit, ): boolean; +export function debug(): void; + /* Template Engine */ export interface UpdateFunctionWithMethods extends UpdateFunction {