tea aims to provide packaging primitives. This library is a route to that goal. libtea can install and provide sandboxed environments for packages that have no effect on the wider system without you or your user needing to install tea/cli.

$ npm install @teaxyz/lib

Or with Deno:

import * as tea from "https://raw.github.com/teaxyz/lib/v0/mod.ts"

To install and utilize Python 3.10:

import { prefab, semver, hooks } from "tea"
import { exec } from "node:child_process"
const { install, hydrate, resolve } = prefab
const { useSync, useShellEnv } = hooks

// ensure pantry exists and is up-to-date
await useSync()

// define the pkg(s) you want
// see https://devhints.io/semver for semver syntax (~, ^, etc)
const pkg = { project: 'python.org', constraint: semver.Range("~3.10") }
// hydrate the full dependency tree
const { pkgs: tree } = await hydrate(pkg)
// resolve the tree of constraints to specific package versions
const { installed, pending } = await resolve(tree)

for (const pkg of pending) {
  const installation = await install(pkg)
  // ^^ install packages that aren’t yet installed
  // ^^ takes a logger parameter so you can show progress to the user
  // ^^ you could do these in parallel to speed things up
  // ^^ by default, versioned installs go to ~/.tea, separated from the user’s system. The install location can be customized, see next section.
  await link(installation)
  // ^^ creates v*, vx, vx.y symlinks ∵ some packages depend on this
  installed.push(installation)
}

const { map, flatten } = useShellEnv()
const env = flatten(map(installed))

exec("python -c 'print(\"Hello, World!\")'", { env })

// the above is quite verbose, but we’ll provide a façade pattern soon

All of tea’s packages are relocatable so you can configure libtea to install wherever you want:

import { hooks, Path } from "tea"
const { useConfig } = hooks

useConfig({ prefix: Path.home().join(".local/share/my-app") })
// ^^ must be done before any other libtea calls

// now if you install python you’ll get:
//     /home/you/.local/share/my-app/python.org/v3.10.11/bin/python

We use a hook-like pattern because it is great. This library is not itself designed for React.

If the user has no existing tea/cli or you use your own prefix then the pantry must be sync’d with useSync() at least once. useSync requires either git or tar to be in PATH. We’ll remove this requirement with time.

We have our own implementation of semver because open source has existed for decades and Semantic Versioning is much newer than that. Our implementation is quite compatible but not completely so. Use our semver with with libtea. Our implementation is 100% compatible with strings output from node’s own semver.

Setting useConfig() is not thread safe. Thus if you are using web workers you must ensure the initial call to useConfig() is called on the main thread before any other calls might happen. We call it explicitly in our code so you will need to call it yourself in such a case. This is not ideal and we’d appreciate your help in fixing it.

There is minimal magic, tea/cli has magic because the end-user appreciates it but libraries need well defined behavior. We will provide a façade patterns to make life easier, but the primitives of libtea require you to read the docs to use them effectively.

We can install anything in the pantry.

If something you need is not there, adding to the pantry has been designed to be an easy and enjoyable process. Your contribution is both welcome and desired!

We would be thrilled to hear your ideas† or receive your pull requests.

† discussions

The code is written with Deno (just like tea/cli) but is compiled to a node package for wider accessibility (and ∵ tea/gui is node/electron)

We would love to port this code to every language. We are deliberately keeping the scope tight. Probably we would prefer to have one repo per language.

tea has sensible rules for how packages are defined and installed so writing a port should be simple.

Open a discussion to start.

deno task test --coverage=cov_profile
deno coverage cov_profile --lcov --output=cov_profile.lcov
tea genhtml -o cov_profile/html cov_profile.lcov
open cov_profile/html/index.html