npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@cto.ai/ops-ctrl-forge

v1.1.0

Published

cto.ai local developer tools

Downloads

13

Readme

@cto.ai/ops-ctrl-forge

cto.ai local developer tools

Status

WIP - do not use

API

This is an ESM module.

forge(opts) => instance

Initialize a forge instance

Options:

  • dockerMissingRetry Optional Default: false. Each of the instance methods (init, build, run)is an async function generator. If Docker is not installed, or if it's installed but not running this will cause an instance method that relies on Docker to reject. Set this to true to instead yield an information object with label: docker-not-found or docker-not-running along with a retries property containing total retries. In either of these cases execution will be paused until iter.next is explicitly called. Calling iter.next({ retry: true }) in this scenario will trigger a retry and if succesful execution will continue. Calling iter.next({ retry: false }) will trigger the usual error. Below is an example of this advanced use case:
const instance = forge({dockerMissingRetry: true})
const iter = instance.build(buildOptions)
for await (const info of iter) {
  if (info.isDockerProblem) {
    const retry = await someUserInput()
    if (info.retries < 10) await iter.next({ retry }) // triggers retry if `retry` is true
    else await iter.next({ retry: false }) // trigger an error
  }
  // do more stuff with other info objects
}

instance.init()

Currently throws ERR_NOT_IMPLEMENTED error.

instance.build(opts) => Async Iterable

Create a build from an Op folder, tar buffer or tar stream (gzipped tars are also accepted). This function is an async function generator and yields info objects as the build operation progresses. These can be consumed like so:

for await (const info of instance.build(buildOptions)) {
  // process info objects
}

Lifecycle:

The yielded info objects represent the phases or status information of the build operation, each has a label property describing the phase or status. The possible labels, in order, are as follows:

  • warning - These may occur during the manifest normalization phase. Contains: {label, code, message, isForgeWarning, isDockerProblem, retries}. The isForgeWarning property is always true. See warnings.js for warning codes and messages. Only Docker related warnings will have the isDockerProblem and retries properties.
  • building - Indicates that a particular selected item in the manifest is now being built. Contains {label, name, version}
  • docker-output - These info objects contain the lines of output and status updates from docker, there can be any number of these info objects depending on the amount of docker output. Contains {type, label, output} where type may be stream for general output or status for status updates.
  • built - Indicates that a particular selected item in the manifest has been built. Contains {label, type, name, version, isPublic, tag, run, publish}. The run and publish properties contain the namespace that would be used to reference the image when running or publishing.

Options:

  • op Required - string, Buffer or Stream. If a string it must be an absolute path to an Op folder. A Buffer must contain a tarball of an Op and a stream must be a read stream of an Op tar ball.
  • api Required - string. The CTO.ai API URL. Example: https://www.stg-platform.hc.ai/api/v1
  • registry Required - string. The Docker hub host. Example: registry.cto.ai
  • select Required - array. The names of commands, pipelines or services to build from an op manifest file. Must have at least one matching name.
  • tokens Required - object. A tokens object, see ops-account-ctrl
  • team Required - string. The team that the Op belongs to, this will be used as part of the image build tag name.
  • cache Optional Default: true - boolean. Set to false to set the --no-cache flag for the Docekr image build.

instance.run()

Currently throws ERR_NOT_IMPLEMENTED error.

Error Handling

Instance methods are async generator functions. Any errors therefore cause a rejection to occur, which when used in an async context (async function or ESM TLA) can be wrapped in a try catch and then handled and/or propagated. The usage pattern is as follows (using instance.build as an example but the same applies to all methods):


try { 
  for await (const info of instance.build(buildOptions)) {
    // process info objects
  }
} catch (err) {
  // rethrow non-forge errors
  if (!err.isForgeError) throw err
  // use err.code to decide what to do with the error
}

See errors.js for an error code reference.

Engines

  • Node 12.4+
  • Node 14.0+

Development

Test:

npm test

Visual coverage report (run after test):

npm run cov

Lint:

npm run lint

Autoformat:

npm run lint -- --fix

Releasing

For mainline releases:

npm version <major|minor|patch>
git push --follow-tags

For prereleases:

npm version prerelease
git push --follow-tags

License

MIT