https://github.com/dy/spect
Observable selectors in DOM
https://github.com/dy/spect
aspects live-collection selector-observer spect
Last synced: 11 months ago
JSON representation
Observable selectors in DOM
- Host: GitHub
- URL: https://github.com/dy/spect
- Owner: dy
- License: mit
- Created: 2019-03-31T15:32:02.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2025-01-18T20:53:51.000Z (over 1 year ago)
- Last Synced: 2025-05-19T21:02:30.948Z (about 1 year ago)
- Topics: aspects, live-collection, selector-observer, spect
- Language: JavaScript
- Homepage: https://dy.github.io/spect
- Size: 5.3 MB
- Stars: 79
- Watchers: 4
- Forks: 8
- Open Issues: 5
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 
spect 
> Observe selectors in DOM.
#### _`spect( container=document, selector, handler? )`_
Observes _`selector`_ in _`container`_, invokes `handler` any time matching elements appear.
Handler can return a teardown function, called for unmatched elements.
Returns live collection of elements.
```js
import spect from 'spect';
// assign aspect
const foos = spect('.foo', el => {
console.log('connected');
return () => console.log('disconnected');
});
// modify DOM
const foo = document.createElement('div');
foo.className = 'foo';
document.body.append(foo);
// ... "connected"
foo.remove();
// ... "disconnected"
```
#### _`spect(element[s], handler)`_
Listens for connected/disconnected events for the list of elements. (alternative to [fast-on-load](https://www.npmjs.com/package/fast-on-load))
```js
const nodes = [...document.querySelectorAll('.foo'), document.createElement('div')];
// assign listener
spect(nodes, el => {
console.log("connected");
return () => console.log("disconnected");
});
document.body.appendChild(nodes.at(-1))
// ... "connected"
nodes.at(-1).remove()
// ... "disconnected"
```
### Live Collection
Spect creates live collection of elements matching the selector. Collection extends Array and implements Set / HTMLColection interfaces.
```js
const foos = spect(`.foo`);
// live collection
foos[idx], foos.at(idx) // Array
foos.has(el), foos.add(el), foos.delete(el) // Set
foos.item(idx), foos.namedItem(elementId) // HTMLCollection
foos.dispose() // destroy selector observer / unsubscribe
```
### Technique
It combines selector parts indexing from [selector-observer](https://github.com/josh/selector-observer) for simple queries and animation events from [insertionQuery](https://github.com/naugtur/insertionQuery) for complex selectors.
Simple selector is id/name/class/tag followed by classes or attrs.
* `#a`, `.x.y`, `[name="e"].x`, `*`, `a-b-c:x` - simple selectors.
* `a b`, `#b .c` - complex selectors.
## Alternatives
[element-behaviors](https://github.com/lume/element-behaviors),
[insertionQuery](https://github.com/naugtur/insertionQuery),
[selector-observer](https://github.com/josh/selector-observer),
[qso](https://www.npmjs.com/package/qso),
[qsa-observer](https://www.npmjs.com/package/qsa-observer),
[element-observer](https://github.com/WebReflection/element-observer),
[livequery](https://github.com/hazzik/livequery),
[selector-listener](https://github.com/csuwildcat/SelectorListener),
[mutation-summary](https://github.com/rafaelw/mutation-summary),
[fast-on-load](https://ghub.io/fast-on-load),
[selector-set](https://github.com/josh/selector-set),
[rkusa/selector-observer](https://github.com/rkusa/selector-observer).
[css-chain](https://github.com/sashafirsov/css-chain)