actions/cache-apt-pkgs-action
1
0
Fork 0
mirror of https://github.com/awalsh128/cache-apt-pkgs-action.git synced 2026-11-13 21:36:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document Manifest and ManifestEntry public members

Browse source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
awalsh128 2026-11-08 15:19:12 -08:00
parent 2e80d3bfa8
commit 4759a96fb1
1 changed files with 51 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
src/manifest.ts
View file

@ -2,15 +2,32 @@ import fs from "node:fs";
import { CacheKey } from "./cache.js";
import { packageNameFromJSON, PackageName } from "ts-apt";
/** One installed package and the files archived for it in the cache. */
export class ManifestEntry {
/** Installed package, with the version and arch apt resolved. */
readonly packageName: PackageName;
/**
* Files installed by the package, relative to `/` (no leading slash) so they
* can be passed straight to tar. Sorted for stable output. Empty for
* packages without files (e.g. metapackages), which get no archive.
*/
readonly filepaths: string[];
/**
* @param packageName Installed package.
* @param filepaths Root-relative file paths; copied and sorted.
*/
constructor(packageName: PackageName, filepaths: string[] = []) {
this.packageName = packageName;
this.filepaths = [...filepaths].sort((a, b) => a.localeCompare(b));
}
/**
* Creates an entry from its parsed JSON form.
*
* @param json Parsed JSON object as written by {@link Manifest.writeToFile}.
* @returns The deserialized entry.
*/
static fromJSON(json: any): ManifestEntry {
return new ManifestEntry(
packageNameFromJSON(json.packageName),
@ -19,14 +36,35 @@ export class ManifestEntry {
}
}
/**
* Record of the packages stored in a cache, written alongside the archives.
*
* Restore reads it to find each package's archive and to report outputs.
*/
export class Manifest {
/**
* @param created When the manifest was created.
* @param entries Packages in the order apt installed them. Restore relies on
* this order because install scripts can depend on earlier packages
* (see issue #196).
* @param cacheKey Key the cache was saved under.
*/
constructor(
/** When the manifest was created. */
public readonly created: Date,
/** Packages in the order apt installed them. */
public readonly entries: ManifestEntry[],
/** Key the cache was saved under. */
public readonly cacheKey: CacheKey,
) {}
// Static factory method
/**
* Creates a manifest from its parsed JSON form.
*
* @param json Parsed JSON object as written by {@link Manifest.writeToFile}.
* Its `cacheKey` is the serialized string from {@link CacheKey.toJSON}.
* @returns The deserialized manifest.
*/
static fromJSON(json: any): Manifest {
return new Manifest(
new Date(json.created),
@ -41,11 +79,23 @@ export class Manifest {
);
}
/**
* Reads and parses a manifest file.
*
* @param filePath Path to a manifest JSON file.
* @returns The parsed manifest.
* @throws Error when the file can't be read or isn't a valid manifest.
*/
static async readFromFile(filePath: string): Promise<Manifest> {
const content = await fs.promises.readFile(filePath, "utf-8");
return Manifest.fromJSON(JSON.parse(content));
}
/**
* Writes the manifest as pretty-printed JSON, replacing any existing file.
*
* @param filePath Destination path.
*/
async writeToFile(filePath: string): Promise<void> {
await fs.promises.writeFile(
filePath,