npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

stanz

v8.1.31

Published

javascript library for listening to data changes of child objects

Downloads

138

Readme

Stanz 8

Using the documentation

Introduction

Stanz is a JavaScript library for monitoring property changes in objects and arrays and executing corresponding actions when properties change.

Features and Advantages

  • Lightweight and easy-to-use library
  • Supports observing property changes in objects and arrays
  • Supports asynchronous observation and batch event triggering
  • Compatible with existing JavaScript code and frameworks, no dependencies

Installation

You can install the Stanz library using the following methods:

  • Directly include it in HTML:
<script src="https://cdn.jsdelivr.net/npm/stanz/dist/stanz.min.js"></script>
  • Install via npm:
npm install stanz
# Or using yarn: yarn add stanz

Basic Concepts

Before using the Stanz library, it's important to understand some basic concepts:

  • Instance : The object or array instance that Stanz operates on.
  • Watch : Use the watch method to monitor changes in instance properties.

Please open the debug mode and visit the corresponding file in the examples directory to quickly understand the usage of stanz. Click here to access the online example of "watch", which is particularly useful for understanding the functionality of stanz.

Creating an Instance

To use the Stanz library, you first need to create an instance object. You can create an instance object using the stanz function.

const stanz = require("stanz"); // If using HTML, you can directly use `stanz`

const data = stanz({
  name: "John",
  age: 30,
});

console.log(data.name); // Output: John
console.log(data.age); // Output: 30

Observing Property Changes

You can use the watch method to observe property changes in instance objects. When the value of a property changes, the corresponding callback function will be triggered.

const data = stanz({
  name: "John",
  age: 30,
});

data.watch((e) => {
  console.log("Property changed:", e);
});

data.name = "Mike"; // Property changed: { type: "set", path: [], name: "name", value: "Mike", oldValue: "John" }

In the example above, we use the watch method to observe property changes in the data instance object. When the value of the name property changes, the triggered callback function will output the corresponding change information.

Observing Property Changes in Sub-objects

The watch method can also observe property changes in sub-objects, including nested sub-objects. When the value of a property in a sub-object changes, the corresponding callback function will be triggered.

const data = stanz({
  name: "John",
  age: 30,
  mother: {
    name: "Jennifer",
    age: 50,
  },
});

data.watch((e) => {
  console.log("Property changed:", e);
});

data.mother.age = 51; // Property changed: { type: "set", path: [Proxy(mother)], name: "age", value: 51, oldValue: 50 }

The above example demonstrates how to use the watch method to observe property changes in the data instance object. When the age property of the mother object changes, the corresponding change information will be output.

Not Observing Properties Starting with "_"

By default, Stanz instances do not observe properties starting with "". These properties are considered private. Modifying properties starting with "" or their sub-object properties will not trigger the watch function.

const data = stanz({
  name: "John",
  _age: 30,
});

data.watch((e) => {
  console.log("Property changed:", e);
});

data._age = 51; // Does not trigger the watch function

Observing Array Changes

The Stanz library not only supports observing property changes in objects but also in arrays.

const data = stanz([1, 2, 3]);

data.watch((e) => {
  console.log("Array changed:", e);
});

data.push(4); // Array changed: { type: "array", name: "push", target: [1, 2, 3, 4], path: [], args: [4] }

In the example above, we use the watch method to observe changes in the data array. When the push method is called to add a new element to the array, the corresponding change information will be output.

Similarly, you can also observe property changes in sub-objects:

const data = stanz({
  name: "John",
  age: 30,
  children: [
    {
      name: "Tom",
      age: 6,
    },
  ],
});

data.watch((e) => {
  console.log("Property changed:", e);
});

data.children.push({
  name: "Jack",
  age: 1,
}); // Array changed: { type: "array", name: "push", target: Proxy(children), path: [Proxy(children)], args: [{name:"Jack",age:1}] }

Observing Property Deletions

In addition to observing property modifications, you can also observe property deletions by using the delete keyword.

const data = stanz({
  name: "John",
  age: 30,
});

data.watch((e) => {
  console.log("Property changed:", e);
});

delete data.name; // Property changed: { type: "delete", target: Proxy(data), path: [], value: undefined, oldValue: "John" }

The above example demonstrates how to observe property deletions using the watch method. When the name property is deleted, the corresponding change information will be output.

Update Control

The Stanz library allows control over property updates. You can temporarily disable triggering callback functions for property updates using the _update property.

const data = stanz({
  name: "John",
  age: 30,
});

data.watch((e) => {
  console.log("Property changed:", e);
});

data._update = false;

data.name = "Mike"; // Does not trigger the property change callback

data._update = true;

data.name = "Tom"; // Property changed: { type: "set", target: { name: "Tom", age: 30 }, path: ["name"], value: "Tom", oldValue: "John" }

In the example above, we use the _update property to control property updates. When it is set to false, the callback function for property changes will not be triggered. When it is set to true, the callback function for property changes will be triggered.

Unwatching

In addition to deleting specific watchers, you can also cancel the observation of properties by calling the unwatch method.

const data = stanz({
  name: "John",
  age: 30,
});

const wid = data.watch((e) => {
  console.log("Property changed:", e);
});

data.name = "Mike"; // Property changed: { type: "set", target: { name: "Mike", age: 30 }, path: ["name"], value: "Mike", oldValue: "John" }

data.unwatch(wid); // Cancel observation of all properties

data.name = "Tom"; // No longer outputs property change information

The above example demonstrates how to cancel the observation of properties by calling the unwatch method. After canceling the observation, modifications to the properties will no longer trigger the corresponding callback function.

Advanced Stanz