ZT Library

ZT Library is a lightweight, modular JavaScript utility library designed to help developers:

• Observe DOM mutations efficiently
• Detect when elements appear/disappear
• Handle conditional triggers
• Manage cookies and storage
• Create reactive DOM behavior
• Provide optional debugging through an env‑controlled logger

It is written with ES Modules and is compatible with modern browsers.

Features

MutationObserver Utilities

• Observe DOM changes efficiently.
• Track added/removed elements, attribute changes, and text content updates.

Element Appearance Utilities

• onAppearAll(selectors, callback, options): Wait until all selectors are present in the DOM.
• onAppearAny(selectors, callback, options): Wait until any selector is present in the DOM.

Conditional Triggers

• triggerOn(config, callback): Execute callbacks based on DOM conditions, URL checks, timeouts, intervals, or logical AND/OR conditions.

Storage Utilities

• localStorage: get, set, del
• sessionStorage: get, set, del

Cookie Utilities

• utils.cookie.set(name, value, days): Set a cookie with optional expiration.
• utils.cookie.get(name): Get a cookie value.
• utils.cookie.del(name): Delete a cookie.

Object Utilities

• patch(target, source): Merge properties from a source object into a target object.

Installation

From NPM

npm i @zilker-trail/zt-library

Usage Examples

Observing DOM Changes

const observer = ztLibrary.createObserver((node, mutationType) => {
  console.log('Mutation detected:', mutationType, node);
}, { childList: true, subtree: true });

Wait for Elements

ztLibrary.onAppearAll(['#header', '.menu'], elements => {
  console.log('All elements appeared:', elements);
});

ztLibrary.onAppearAny(['.modal', '.popup'], element => {
  console.log('One of the elements appeared:', element);
});

Trigger on Conditions

ztLibrary.triggerOn({
  condition: 'domElement',
  options: { selector: '#main-content', timeout: 5000 }
}, () => {
  console.log('Main content appeared!');
});

ztLibrary.triggerOn({
  condition: 'url',
  type: 'pass',
  options: { includes: '/dashboard' }
}, () => {
  console.log('User is on the dashboard page');
});

Cookies

ztLibrary.utils.cookie.set('userToken', 'abc123', 7);
const token = ztLibrary.utils.cookie.get('userToken');
ztLibrary.utils.cookie.del('userToken');

Local Storage

ztLibrary.utils.localStorage.set('theme', 'dark');
const theme = ztLibrary.utils.localStorage.get('theme');
ztLibrary.utils.localStorage.del('theme');

Patching Objects

const obj = { a: 1 };
ztLibrary.utils.patch(obj, { b: 2, c: 3 });
console.log(obj); // { a: 1, b: 2, c: 3 }

Logging

ztLibrary.setDebuggedMode(bool)

Controlled via the localStorage key zt_debugger.

When enabled, logs info, warnings, and errors to the console for debugging purposes.

Analytics

ztLibrary.setAnalyticsDisabled(bool)

You can disable analytics via the localStorage key zt_analytics.