tcmts.cli.libraries

test/
5 definitions

Types

FoundLibrary type
A library a hub's search found (`/api/search`), with what matched in it.
Library type
A library a branch holds: where it's mounted, and what the record holding it says.
LibraryEntry type
What a namespace's record says of a library it holds, by the name the library is mounted at.

Server

addLibrary (cb: Codebase, o: { name?: string | undefined; source: string; what?: string | undefined; at?: stri…
Add a library: fetch the namespace `what` names on `source` (a release, or a namespace hash), or the release `source` names as announced (`@alice.dev/geo@1.2.0`), with everything it names, and mount it read-only at `at` (default defaultMount), recorded beside it. It's called `name`, else after its package (libraryName): a library by hash has no package to be called after.
fetchFromSources (cb: Codebase, sources: string[], what: string, open?: (source: string) => Promise<Remote> | Remote…
Find `what` (a release, or a namespace hash) on the first of `sources` that has it, then fetch its namespace from whichever has that, trying each in turn: what arrives is checked by hash, so it's no matter which answers. Each that doesn't is said, and the next tried. `open` opens a source (default `openRemote`: a remote's name, a URL, a directory; a hub gives `publicRemote`).
libraryEffects (cb: Codebase, rows: NameRow[]) => { reaches: Map<Effect, string[]>; unknown: string[]; }
Where a library's code reaches outside itself, worked out from the code, not from what anyone says of it: by effect, the definitions whose own code does, or which use a package's export that does (`fetchTiles (node-fetch)`). `unknown`: packages whose code couldn't all be followed (a computed import, `eval`), so may reach more. Its tests aren't counted; `rows` are named as in the library.
libraryReport (cb: Codebase, before: NameRow[], after: NameRow[]) => ApiReport | undefined
How a library's API changed between two versions, as a release says it, if both are packages (a `manifest`).
listLibraries (cb: Codebase) => Promise<void>
`tcm lib`: the libraries this branch holds, each with what it is, where it comes from, and what its author and the people the codebase trusts say of it (yanks, advisories, reviews).
printEffects (now: { reaches: Map<Effect, string[]>; unknown: string[]; }, was?: { reaches: Map<Effect, string[]…
A library's effects (libraryEffects), a line each; against what it reached before (`was`, an upgrade), only what's new or gone.
removeLibrary (cb: Codebase, which: string) => Library
Remove a library: its names and its entry in the record; refused while code outside it uses what only it names.
searchHub (cb: Codebase, o: { query: string; hub?: string | undefined; }) => Promise<FoundLibrary[]>
`tcm lib search <query> [--hub <url>]`: ask a hub what its libraries hold that matches `query` (a name, words in docs, or `:a type`), and say each library with what matched and its `tcm lib add` line: the hub `hubToAsk` says.
setSources (cb: Codebase, which: string, o: { add?: string | undefined; rm?: string | undefined; }) => void
`tcm lib sources`: add a place to fetch a library from (tried after the others), or remove one (not its last). Its record changes; its names don't.
upgradeLibrary (cb: Codebase, o: { library: string; what?: string | undefined; source?: string | undefined; check?…
Move a library to another version (`what`: a release or a namespace hash; default its package's newest release, from its sources, `source` first if given): its API's changes said first, then, unless `check`, its names replaced by the new version's in one update, each definition patched to the one replacing it, so code using it follows (what doesn't typecheck against it goes to todo). Refused while code uses something the new version doesn't have.
withRecord (cb: Codebase, rows: NameRow[], record: string, entries: Record<string, LibraryEntry>) => NameRow[]
`rows`, with the record at `record` holding `entries` (none: no record).

Shared

DEFAULT_HUB "https://tcm.codes/hub"
The hub `tcm lib search` asks when it's given none and keeps none: tcm's own.
EFFECT_WORDS Record<Effect, string>
What each effect is called, said to someone deciding whether to use a library.
HUB_SETTING "lib.hub"
The codebase setting keeping the hub `tcm lib search` asks.
RECORD "libraries"
A namespace's record of the libraries it holds is the JSON file of this name in it: `tcmts.lib.libraries`.
announcedSpec (source: string, what: string | undefined) => { who: string; what?: string | undefined; } | undefin…
What `tcm lib add <source> [what]` names as announced: `@<handle or DID>/<package>[@<version>]`, or `@<handle or DID>` with the release as `what`. Undefined for any other source.
announcer (l: Pick<LibraryEntry, "did" | "handle">) => string
Who announced a library: `@handle`, or their DID when no handle is kept.
defaultMount (paths: string[], name: string, mounts?: string[]) => string
Where a library is mounted unless it's said: `lib.<name>` in the project's root namespace (`tcmts.lib.geo`). The libraries mounted already (`mounts`), their record and the trust list (`lib.trust`) aren't the project's code: a codebase holding only `lib.react` mounts the next at `lib.server`.
fetchAnnounced (cb: Codebase, who: string, what: string, o?: { first?: string | undefined; also?: string[] | undef…
Fetch a release `who` announced (`what`: `geo@1.2.0`, or `geo` for its highest version): found among their `codes.tcm.release` records, its namespace fetched by hash from the record's sources (`first` ahead of them, `also` after), and checked by re-hashing as it arrives.
hubToAsk (store: Pick<Store, "getSetting" | "setSetting">, hub: string | undefined) => string
The hub `tcm lib search` asks: the one given (kept for next time, a codebase setting), else the one kept, else tcm's own (`DEFAULT_HUB`, which isn't kept: a codebase that never chose one follows tcm's).
inLibrary (libraries: Library[], path: string) => boolean
Whether `path` is one of these libraries' names.
librariesIn (store: Store) => Library[]
The libraries this branch holds, from its records: outermost only (a library's own libraries are part of it).
librariesOf (rows: Pick<NameRow, "hash" | "kind" | "path">[], textOf: (hash: string) => string) => Library[]
The libraries some names hold (a branch's, or a past namespace's), from the records among them, each read with `textOf`: outermost only.
librariesRead WeakMap<Store, { key: string; libraries: Library[]; }>
The libraries read last, by store: records rarely change, and the guard asks for every name changed.
libraryGuard (store: Store) => (path: string) => void
The guard keeping a codebase's libraries read-only (`Store.guard`): their names, and the records saying what each is, change only through `tcm lib`.
libraryLabel (l: Pick<LibraryEntry, "namespace" | "release">) => string
What a library is, said briefly: its release, or its namespace's hash.
libraryName (release: string) => string
What a library is called unless it's said: its package's name, without its scope or version, as a name can be (`@alice/geo-tools@1.2.0`: `geo_tools`).
libraryNamed (store: Store, which: string) => Library
The library `which` names: its mount (`tcmts.lib.geo`), or its own name if only one library has it (`geo`).
mountedAsAdded (store: Store, lib: Library) => boolean
Whether a library's names are still the namespace it was added as: what's mounted, hashed as a namespace.
mountedRows (store: Store, lib: Library) => NameRow[]
A library's names as they're mounted now, named as in the library itself (`area`, not `app.lib.geo.area`).
namesNow (store: Store) => NameRow[]
This branch's names, each with the text version it shows: what `setBranchNames` takes to keep them as they are.
parseRecord (text: string) => Record<string, LibraryEntry>
A record's entries, by mount name: what isn't one (not JSON, or an entry without a namespace and a source) is left out.
projectRoot (paths: string[]) => string
The namespace a codebase's own code is in: its one top-level namespace, or none if it has several.
recordAt (store: Store, record: string) => Record<string, LibraryEntry>
The entries of the record at `record` on this branch (none if there's none).
recordFor (mount: string) => string
A record's path, for a mount: the `libraries` file beside it.
recordText (entries: Record<string, LibraryEntry>) => string
A record's text: its entries by name, one field a line, so a merge or a diff reads it line by line.
releaseNamespace (from: { getCausals(hashes: string[]): Causal[] | Promise<Causal[]>; getNamespaces(hashes: string[]…
The namespace hash a release names: its package's namespace in the history entry it was made at. `from` is a remote, or a store (this codebase), which has the same two lookups.
resolveLibrary (remote: Remote, what: string) => Promise<{ namespace: string; release?: string | undefined; }>
What `what` names on a remote: a release (`geo@1.2.0`, or `geo` for its newest), or a namespace by its whole hash (`#…`). A release is its package's namespace in the history entry it names.
upgradeMap (before: Pick<NameRow, "hash" | "kind" | "path">[], after: Pick<NameRow, "hash" | "kind" | "path">[…
What an upgrade from one version of a library to another does to its names: each definition of the old one that the new one has another at the same name (and in the same space) is replaced by it; the rest of the old one that the new one doesn't have at all is gone.
usersOf (store: Store, lib: Library, only?: Set<string> | undefined) => string[]
Code outside a library that uses what only it names (of `only`, if given): what removing it (or those) would leave using code nothing names.
within (path: string, mount: string) => boolean
Whether `path` is `mount` or a name under it.