Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/neoncitylights/piper
TypeScript library to make walking through the DOM easier. Currently supports parsing <dl> and <table> elements.
https://github.com/neoncitylights/piper
Last synced: 2 days ago
JSON representation
TypeScript library to make walking through the DOM easier. Currently supports parsing <dl> and <table> elements.
- Host: GitHub
- URL: https://github.com/neoncitylights/piper
- Owner: neoncitylights
- License: mit
- Created: 2022-11-17T22:28:01.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-24T21:20:04.000Z (5 months ago)
- Last Synced: 2024-10-06T13:15:23.777Z (about 1 month ago)
- Language: TypeScript
- Homepage: https://neoncitylights.github.io/piper/
- Size: 622 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @neoncitylights/piper
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@neoncitylights/piper)
[](https://github.com/neoncitylights/piper/deployments/activity_log?environment=github-pages)
[](https://github.com/neoncitylights/piper/actions/workflows/main.yml)
This library provides some utilities for walking through specific HTML elements and turning into machine-readable data.
## Install
```
npm install @neoncitylights/piper
```
## Documentation
[Auto-generated API documentation is available](https://neoncitylights.github.io/ts-piper/).
### API Reference
#### Walker functions
* `fn`: # walkDescriptionList.**walkDescriptionList**<*K*, *V*>(*element*, *termCallback*, *detailsCallback*): *Map* • [source](./src/walkDescriptionList.ts)
* `fn`: # walkTable.**walkTable**(*table*): *TableRow[][]* • [source](./src/walkTable.ts)
#### Walker helper utilities
* `T`: # walkTable.**TableBodies** • [source](./src/walkTable.ts)
* `T`: # walkTable.**TableRow** • [source](./src/walkTable.ts)
* `C`: # walkTable.**TableModelError** • [source](./src/walkTable.ts)
* `fn`: # walkTable.**collectProperties**(*table*): *string*[] • [source](./src/walkTable.ts)
* `fn`: # walkTable.**collectTableBodies**(*table*): [*TableBodies*](./src/walkTable.ts) • [source](./src/walkTable.ts)
* `fn`: # walkTable.**collectTableRows**(*table*): [*TableRow*](src/walkTable.ts) • [source](./src/walkTable.ts)
#### Table utilities
* `T`: # tableUtils.**HTMLTableLikeElement** • [source](./src/tableUtils.ts)
* `fn`: # tableUtils.**isTableLikeElement**(*element*): *element* is *HTMLTableRelatedElement* • [source](./src/tableUtils.ts)
* `fn`: # tableUtils.**getTableCaption**(*table*): *string* • [source](./src/tableUtils.ts)
* `fn`: # tableUtils.**getClosestParentTable**(*element*): *HTMLTableElement*|*undefiend* • [source](./src/tableUtils.ts)
* `fn`: # tableUtils.**getClosestParentTableByRow**(*row*): *HTMLTableElement* • [source](./src/tableUtils.ts)
## Usage
```ts
import { walkDescriptionList, walkTable } from '@neoncitylights/piper';
// walking through a description list
let descListElement = document.querySelector('dl#my-description-list') as HTMLDListElement;
let descList = walkDescriptionList(
descListElement,
(term) => term.textContent ?? '',
(details) => details.textContent ?? '');
// walking through a table
let timezonesTable = document.querySelector('table') as HTMLTableElement;
let timezones = walkTable(timezonesTable);
```
## Full examples
### Walking through a description list (`
- `)
- Extensions
- Remove, install, and change settings of extensions
- Site activity
- Learn how visitors are using your site
- Layout and appearance
- Change how your site appears to viewers
- Privacy
- Decide who is able to access your site
- Security and storage
- Backup, update, and protect your site
```html
```
```ts
import { walkDescriptionList } from '@neoncitylights/piper';
const prefsElement = document.getElementById('prefs') as HTMLDListElement;
const prefs = walkDescriptionList(prefsElement,
(term) => term.textContent ?? '',
(details) => details.textContent ?? '');
```
```json
{
"Extensions": "Remove, install, and change settings of extensions",
"Site activity": "Learn how visitors are using your site",
"Layout and appearance": "Change how your site appears to viewers",
"Privacy": "Decide who is able to access your site",
"Security and storage": "Backup, update, and protect your site."
}
```
### Walking through a table (``)
```html
Name
Explanation
America/Costa_Rica
name of country used because the name of the largest city (and capital city) San José is ambiguous
America/New_York
Space replaced with underscore
Asia/Kolkata
name of city of Kolkata used, because it was the most populous city in the zone at the time the zone was set up, though this is no longer true[17]
Asia/Sakhalin
name of island used, because largest city, Yuzhno-Sakhalinsk, has more than 14 characters
America/Bahia_Banderas
"de" removed from Bahia de Banderas, because correct name has more than 14 characters
Antarctica/DumontDUrville
the apostrophe is removed. The space would normally be replaced with "_", but the name would then exceed 14 characters.
```
```ts
import { walkTable } from '@neoncitylights/piper';
let timezoneTableElement = document.getElementById('timezone-examples') as HTMLTableElement;
let timezoneExamples = walkTable(timezoneTableElement);
```
```json
[
[
{
"Name": "America/Costa_Rica",
"Explanation": "name of country used because the name of the largest city (and capital city) San José is ambiguous"
},
{
"Name": "America/New_York",
"Explanation": "Space replaced with underscore"
},
{
"Name": "Asia/Kolkata",
"Explanation": "name of city of Kolkata used, because it was the most populous city in the zone at the time the zone was set up, though this is no longer true[17]"
},
{
"Name": "Asia/Sakhalin",
"Explanation": "name of island used, because largest city, Yuzhno-Sakhalinsk, has more than 14 characters"
},
{
"Name": "America/Bahia_Banderas",
"Explanation": "de removed from Bahia de Banderas, because correct name has more than 14 characters"
},
{
"Name": "Antarctica/DumontDUrville",
"Explanation": "the apostrophe is removed. The space would normally be replaced with \"_\", but the name would then exceed 14 characters."
}
]
]
```
## License
This library is licensed under the [MIT License](./LICENSE).