rhachet-artifact

declare artifacts with a simple, universal contract

purpose

• simplify usage of artifacts
• standardize shape of artifacts

install

npm install rhachet-artifact

use

usage should typically be implemented via an extension library

here's a few examples

• rhachet-artifact-git

here's a breakdown of how though

declare the resource to use as an artifact

lets use a zip file as an artifact, for example

interface ZipFile {
  /**
   * .what = where this file is persisted
   */
  uri: string;

  /**
   * .what = the hash of the content for comparison
   */
  hash: string;

  /**
   * .what = the actual contents, in { [filename]: content } format
   */
  contents: Record<string, string>;
}
class ZipFile extends DomainEntity<ZipFile> implements ZipFile {
  public static unique = ['uri'] as const;
}

declare how to create artifacts of that resource

create a generator which will fillout the get/set/del mechanisms of the artifact.

/**
 * .what = generates a ZipFile Artifact
 * .why = simplify usage of zip files via artifact contract
 */
export const genArtifactZipFile = (
  ref: { uri: string },
): Artifact<typeof ZipFile, Record<string, string>> => {
  return new Artifact<typeof ZipFile, Record<string, string>>({
    ref,
    get: withExpectOutput(async () => {
      const files = await getZipFile(ref.uri);
      if (!files) return null;

      const buffer = await fs.readFile(ref.uri);
      return new ZipFile({
        uri: ref.uri,
        hash: hashBuffer(buffer),
        files,
      });
    }),
    set: async ({ content }) => {
      const buffer = await setZipFile(ref.uri, content);
      return new ZipFile({
        uri: ref.uri,
        hash: hashBuffer(buffer),
        files: content,
      });
    },
    del: async () => {
      await deleteZipFile(ref.uri);
    },
  });
};

use your artifacts

// 📦 write to a zip artifact
const zipArtifact = genArtifactZipFile({ uri: 'output.zip' });
await zipArtifact.set({
  content: {
    'hello.txt': 'hello world',
    'readme.md': '# this is a zip file',
  },
});

// 📂 read from a zip artifact
const result = await zipArtifact.get().expect('isPresent');
console.log(result.files['hello.txt']);  // → "hello world"
console.log(result.files['readme.md']);  // → "# this is a zip file"

// 🗑 delete the zip artifact
await zipArtifact.del();