eric/twtxt-lib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add support for v2 hashing algorithm.

Browse Source 
update README.md and demo file to be more in sync.
update to v0.10.0.
This commit is contained in:
Eric Woodward
2026-03-29 22:34:43 -04:00
parent d5363c3960
commit c776b5df6a
33 changed files with 2255 additions and 1524 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
README.md
View File

@@ -12,14 +12,30 @@ These functions include:
[metadata](https://twtxt.dev/exts/metadata.html) in the file).
- `loadAndParseTwtxt`: fetches a twtxt file from _the internet_ and parses it into an object (as above).
## Features
- Isomorphic, available as an ([optionally minified](/dist-browser/twtxt-lib.min.js))
[ES6+ library for the browser](/dist-browser/twtxt-lib.js), with NPM and JSR versions coming soon.
or as a package (from [NPM](https://www.npmjs.com/package/twtxt-lib) or
[JSR](https://jsr.io/@itsericwoodward/twtxt-lib)).
- Fully typed and source-mapped (I hope).
- Built as an [ES6 Module](https://caniuse.com/es6-module) (and [ESM only](https://antfu.me/posts/move-on-to-esm-only)).
- Includes sample files and an [interactive demo](https://twtxt-lib.itsericwoodward.com/).
## Installation
This library can be installed in several different ways:
This library can be installed several different ways:
### For the Browser
1. Grab the latest copy of the `twtxt-lib.js` file, either by downloading it from the [git repo](https://git.itsericwoodward.com/eric/twtxt-lib/raw/branch/main/dist-browser/twtxt-lib.js), the [website](https://twtxt-lib.itsericwoodward.com/dist-browser/twtxt-lib.js), or doing a `git clone https://git.itsericwoodward.com/eric/twtxt-lib.git` and pulling it out of the `dist-browser` folder.
- Alternatively, you can grab the minified version from the [same](https://git.itsericwoodward.com/eric/twtxt-lib/raw/branch/main/dist-browser/twtxt-lib.min.js) [sources](https://twtxt-lib.itsericwoodward.com/dist-browser/twtxt-lib.min.js).
1. Grab the latest copy of the `twtxt-lib.js` file, either by downloading it from the
[git repo](https://git.itsericwoodward.com/eric/twtxt-lib/raw/branch/main/dist-browser/twtxt-lib.js),
the [website](https://twtxt-lib.itsericwoodward.com/dist-browser/twtxt-lib.js), or by doing a
`git clone https://git.itsericwoodward.com/eric/twtxt-lib.git` and pulling it out of the
`dist-browser` folder.
- Alternatively, you can grab the minified version from the
[same](https://git.itsericwoodward.com/eric/twtxt-lib/raw/branch/main/dist-browser/twtxt-lib.min.js)
[sources](https://twtxt-lib.itsericwoodward.com/dist-browser/twtxt-lib.min.js).
2. Add the newly acquired file to your static site / progressive web app / over-engineered blog.
3. Import the desired function(s) via ESM: `import { hashTwt, loadAndParseTwtxtFile } from "./twtxt-lib.js";`
@@ -27,88 +43,28 @@ This library can be installed in several different ways:
1. Add the package to your project.
- Via [NPM](https://www.npmjs.com/package/twtxt-lib): `yarn add twtxt-lib`
- Via [JSR](https://jsr.io/@itsericwoodward/twtxt-lib): `yarn add jsr:@itsericwoodward/twtxt-lib`
2. Import the desired function(s) into your code: `import { hashTwt, loadAndParseTwtxtFile } from "twtxt-lib";`
## Features
- Isomorphic, available as an ([optionally minified](/dist-browser/twtxt-lib.min.js))
[ES6+ library for the browser](/dist-browser/twtxt-lib.js), with NPM and JSR versions coming soon.
- Fully typed and source-mapped.
- [ES6 Module](https://caniuse.com/es6-module) (and [ESM only](https://antfu.me/posts/move-on-to-esm-only)).
- Includes sample files and an [interactive demo page](https://twtxt-lib.itsericwoodward.com/).
- Via [JSR](https://jsr.io/@itsericwoodward/twtxt-lib):
`yarn add jsr:@itsericwoodward/twtxt-lib`
2. Import the desired function(s) via ESM:
`import { hashTwt, loadAndParseTwtxtFile, parseTwtxt } from "twtxt-lib";`
## Usage
### loadAndParseText
This is arguably the most useful function:
```
import { loadAndParseTwtxtFile } from "/web/dist/twtxt-lib.js";
// run in an IIFE (or event listener) to avoid issues with top-level await
(async () => {
try {
const parsedFile = await loadAndParseTwtxtFile(
"/twtxt-demos/demo-hipster-twtxt.txt",
);
console.log(parsedFile);
} catch (err) {
console.error(err);
}
})();
```
Result:
```
{
"following": [
{
"nick": "demo_hipster",
"url": "https://example.com/demo-hipster-twtxt.txt"
},
{
"nick": "demo_pirate",
"url": "https://example.org/~pirate/twtxt.txt"
},
{
"nick": "demo_sagan",
"url": "https://example.net/~saganos/twtxt.txt"
}
],
"metadata": {
"nick": "demo_hipster",
"url": "https://example.com/demo-hipster-twtxt.txt",
"avatar": "https://i.pravatar.cc/150?img=67",
"description": "Kitsch ut post-ironic, bruh tilde non shabby chic iceland fixie consequat?"
},
"twts": [
{
"content": "Normcore tilde ad selfies, culpa cupping nostrud gatekeep aesthetic PBR&B 3 wolf moon mustache twee.",
"created": "2025-06-02T18:47:01+01:00",
"createdUTC": "2025-06-02T17:47:01.000Z",
"hash": "ymiydvq"
},
{
"content": "Cardigan jean shorts eu 90's. Kitsch knausgaard culpa, marfa mumblecore portland raclette banjo retro exercitation pariatur snackwave williamsburg.",
"created": "2025-07-05T00:17:46+02:00",
"createdUTC": "2025-07-04T22:17:46.000Z",
"hash": "c6bm4sq"
},
...
],
"lastModified": "2026-02-22T20:56:59.000Z"
}
```
When using in a web browser, be aware of potential the potential for issues with [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS).
See the included tests and demo file for more information on how to use it.
### hashTwt
A function that takes the constituent parts of a "twt" and generates an
[extension-compatible hash](https://twtxt.dev/exts/twt-hash.html) for it, which is then returned.
Version 0.10.0 and above includes support for
[V2 of the Hashing Spec](https://git.mills.io/yarnsocial/twtxt.dev/pulls/28):
- A specific hashing version can be provided as an optional argument.
- When no version argument is provided, it defaults to using version 1 for all twts with a created
date before the epoch date (`2026-07-01T00:00:00Z`), and version 2 for all twts created on or
after the epoch.
```
import { hashTwt } from "/web/dist/twtxt-lib.js";
@@ -129,6 +85,10 @@ Hash: 7uftieq
### parseTwtxt
A function that parses a twtxt file string, returning an object with information about the file and
its owner (including generating [hashes](#hashTwt) for each twt and
any [metadata](https://twtxt.dev/exts/metadata.html) in the file).
```
import { base32Encode, hashTwt, loadAndParseTwtxt, parseTwtxt } from "twtxt-lib";
@@ -213,7 +173,74 @@ Result:
}
```
See the included tests and demo file for more information on how to use it.
### loadAndParseText
Aan async function that fetches a `twtxt.txt`-compatible file from a URL and parses it,
returning the extracted data as an object.
```
import { loadAndParseTwtxtFile } from "/web/dist/twtxt-lib.js";
// run in an IIFE (or event listener) to avoid issues with top-level await
(async () => {
try {
const parsedFile = await loadAndParseTwtxtFile(
"/twtxt-demos/demo-hipster-twtxt.txt",
);
console.log(parsedFile);
} catch (err) {
console.error(err);
}
})();
```
Result:
```
{
"following": [
{
"nick": "demo_hipster",
"url": "https://example.com/demo-hipster-twtxt.txt"
},
{
"nick": "demo_pirate",
"url": "https://example.org/~pirate/twtxt.txt"
},
{
"nick": "demo_sagan",
"url": "https://example.net/~saganos/twtxt.txt"
}
],
"metadata": {
"nick": "demo_hipster",
"url": "https://example.com/demo-hipster-twtxt.txt",
"avatar": "https://i.pravatar.cc/150?img=67",
"description": "Kitsch ut post-ironic, bruh tilde non shabby chic iceland fixie consequat?"
},
"twts": [
{
"content": "Normcore tilde ad selfies, culpa cupping nostrud gatekeep aesthetic PBR&B 3 wolf moon mustache twee.",
"created": "2025-06-02T18:47:01+01:00",
"createdUTC": "2025-06-02T17:47:01.000Z",
"hash": "ymiydvq"
},
{
"content": "Cardigan jean shorts eu 90's. Kitsch knausgaard culpa, marfa mumblecore portland raclette banjo retro exercitation pariatur snackwave williamsburg.",
"created": "2025-07-05T00:17:46+02:00",
"createdUTC": "2025-07-04T22:17:46.000Z",
"hash": "c6bm4sq"
},
...
],
"lastModified": "2026-02-22T20:56:59.000Z"
}
```
When using in a web browser, be aware of the potential for issues with
[Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS).
## License