@finbheara/archive-client 0.0.0-stage → 0.1.0

package/dist/types/manager.d.ts

@@ -0,0 +1,94 @@
+import { type LandedFile } from "./assets.js";
+import { type IndexFile } from "./indexes.js";
+import { type Pin } from "./pin.js";
+import { type OpenOptions, type Release, resolveTag } from "./release.js";
+export interface CachedRelease {
+    tag: string;
+    cut: number | undefined;
+    source: string;
+    pinned: boolean;
+    bytes: number;
+    files: {
+        name: string;
+        bytes: number;
+        verified: LandedFile["verified"];
+    }[];
+    indexes: IndexFile[];
+}
+export interface ReleaseList {
+    root: string;
+    repo: string | null;
+    pin: Pin | null;
+    cached: CachedRelease[];
+    published?: string[];
+}
+export interface RemovalPlan {
+    dryRun: boolean;
+    remove: {
+        path: string;
+        bytes: number;
+        why: string;
+    }[];
+    keep: {
+        tag: string;
+        why: string;
+    }[];
+    bytes: number;
+}
+export declare class ReleaseManager {
+    private readonly opts;
+    readonly root: string;
+    constructor(opts?: OpenOptions);
+    cachedTags(): string[];
+    private cached;
+    list(o?: {
+        remote?: boolean;
+    }): Promise<ReleaseList>;
+    fetch(spec: string | number, o?: {
+        assets?: readonly string[];
+    }): Promise<Release>;
+    pin(spec: string | number): Promise<Pin>;
+    unpin(): boolean;
+    current(): {
+        pin: Pin | null;
+        cached: boolean;
+    };
+    config(patch: {
+        repo?: string;
+    }): {
+        repo?: string;
+    };
+    readConfig(): {
+        repo?: string;
+    };
+    add(dir: string, tag: string): Promise<Release>;
+    index(spec: string | number, names?: readonly string[], o?: {
+        force?: boolean;
+    }): Promise<{
+        tag: string;
+        built: {
+            name: string;
+            path: string;
+        }[];
+    }>;
+    private plan;
+    private planRemove;
+    private apply;
+    prune(o?: {
+        keep?: number;
+        dryRun?: boolean;
+    }): RemovalPlan;
+    remove(tag: string, o?: {
+        dryRun?: boolean;
+    }): RemovalPlan;
+    dropIndexes(tag?: string, o?: {
+        dryRun?: boolean;
+    }): RemovalPlan;
+    verify(tag: string): Promise<{
+        file: string;
+        want: string;
+        got: string;
+    }[]>;
+}
+export declare function releases(opts?: OpenOptions): ReleaseManager;
+export { resolveTag };

package/dist/types/people.d.ts

@@ -0,0 +1,65 @@
+import { type StaffRole } from "@finbheara/domain/noun-index";
+import { type NameLevel } from "./dancers-names.js";
+import type { IndexBuilder } from "./indexes.js";
+import type { Release } from "./release.js";
+export interface Taught {
+    school_id: string;
+    school: string | null;
+    name: string;
+    role: string | null;
+    credentials: string[];
+    years: number[];
+    from: number | null;
+    to: number | null;
+    former: boolean;
+    provisional: boolean;
+}
+export interface TdLink {
+    school_id: string;
+    school: string | null;
+    via: string;
+    captured: string;
+}
+export interface Registered {
+    year: number;
+    cat: string;
+    name_printed: string;
+    region: string;
+    region_code: string | null;
+    country: string;
+}
+export interface Sat {
+    kind: "majors" | "feis";
+    event: string | null;
+    year: number | null;
+    seats: number;
+    competitions: number;
+}
+export interface StaffPerson {
+    clrg: number | null;
+    judge_id: number | null;
+    nameLevel: NameLevel | "id";
+    names: string[];
+    taught: Taught[];
+    td_links: TdLink[];
+    register: Registered[];
+    sat: Sat[];
+}
+export interface StaffAnswer {
+    tag: string;
+    asked: string;
+    role: StaffRole;
+    arm: "unique" | "ambiguous" | "none";
+    people: StaffPerson[];
+    refused?: string;
+}
+export declare const staffIndex: IndexBuilder;
+export declare class StaffFinder {
+    private readonly rel;
+    constructor(rel: Release);
+    teacher(asked: string): Promise<StaffAnswer>;
+    adjudicator(asked: string): Promise<StaffAnswer>;
+    private find;
+    private person;
+    private taughtWhere;
+}

package/dist/types/pin.d.ts

@@ -0,0 +1,8 @@
+export interface Pin {
+    tag: string;
+    source: string;
+}
+export declare const pinPath: (root: string) => string;
+export declare function readPin(root: string): Pin | null;
+export declare function writePin(root: string, pin: Pin): void;
+export declare function clearPin(root: string): boolean;

package/dist/types/registrations.d.ts

@@ -0,0 +1,60 @@
+import type { CompAnswer, CompResolver } from "./comps.js";
+import { type DancerAnswer, type DancerQuery } from "./dancers.js";
+import type { Release } from "./release.js";
+export interface RegistrationRow {
+    name: string;
+    order?: string;
+    school?: string;
+    codes: readonly string[];
+    feis: string;
+    year?: number;
+    titles?: Readonly<Record<string, string>>;
+    asOf?: string;
+    [k: string]: unknown;
+}
+export type DancerQueryLike = DancerQuery;
+export interface DancerAnswerLike {
+    arm: "unique" | "ambiguous" | "none";
+    candidates: readonly unknown[];
+    [k: string]: unknown;
+}
+export interface DancerResolverLike {
+    resolve(q: DancerQuery): Promise<DancerAnswerLike | DancerAnswer> | DancerAnswerLike;
+}
+export interface DancerUnavailable {
+    arm: "unavailable";
+    why: string;
+}
+export interface ResolvedRegistration {
+    tag: string;
+    row: RegistrationRow;
+    comps: CompAnswer[];
+    age: {
+        band: string;
+        year: number | null;
+        code: string;
+        from: "comp" | "title";
+    } | null;
+    bands?: string[];
+    dancer: DancerAnswer | DancerAnswerLike | DancerUnavailable;
+    asked?: DancerQueryLike;
+}
+export declare function youngest<T extends {
+    age: string;
+}>(answers: readonly T[]): T | undefined;
+export interface ResolvedDancer {
+    tag: string;
+    asked: DancerQueryLike;
+    put: DancerQueryLike;
+    comp?: CompAnswer;
+    dancer: DancerAnswer | DancerAnswerLike | DancerUnavailable;
+}
+export declare function dancerResolverOf(rel: Release): DancerResolverLike;
+export declare class RegistrationResolver {
+    private readonly rel;
+    private readonly comps;
+    private readonly dancers?;
+    constructor(rel: Release, comps: CompResolver, dancers?: DancerResolverLike | null | undefined);
+    dancer(q: DancerQueryLike): Promise<ResolvedDancer>;
+    resolve(rows: readonly RegistrationRow[]): Promise<ResolvedRegistration[]>;
+}

package/dist/types/release.d.ts

@@ -0,0 +1,70 @@
+import { Database } from "bun:sqlite";
+import { type AssetPlan, type LandedFile, type Receipt, type ReleaseManifest } from "./assets.js";
+import { CompResolver } from "./comps.js";
+import { type ClientOptions } from "./config.js";
+import { DancerResolver } from "./dancers.js";
+import { FeisFinder } from "./feises.js";
+import { type IndexBuilder } from "./indexes.js";
+import { StaffFinder } from "./people.js";
+import { type DancerResolverLike, RegistrationResolver } from "./registrations.js";
+import { type Remote } from "./remote.js";
+import { MajorsFinder, ResultFinder } from "./results.js";
+import { type SchoolReaderChoice, SchoolResolver } from "./schools.js";
+import { type ReleaseSpec } from "./tag.js";
+export interface OpenOptions extends ClientOptions {
+    assets?: readonly string[];
+    remote?: Remote;
+    strict?: boolean;
+    keepCompressed?: boolean;
+    log?: (line: string) => void;
+    builders?: readonly IndexBuilder[];
+    schoolReader?: SchoolReaderChoice;
+    dancerResolver?: DancerResolverLike | null;
+}
+export declare function tagDir(root: string, tag: string): string;
+export declare const receiptPath: (dir: string) => string;
+export declare function readReceipt(dir: string): Receipt | null;
+export declare function resolveTag(spec: string | number | ReleaseSpec, opts?: OpenOptions): Promise<string>;
+export declare class Release {
+    readonly tag: string;
+    readonly cut: number | undefined;
+    readonly fraction: number;
+    readonly dir: string;
+    readonly root: string;
+    readonly manifest: ReleaseManifest;
+    readonly feises: FeisFinder;
+    readonly schools: SchoolResolver;
+    readonly dancers: DancerResolver;
+    readonly results: ResultFinder;
+    readonly majors: MajorsFinder;
+    readonly staff: StaffFinder;
+    readonly comps: CompResolver;
+    readonly registrations: RegistrationResolver;
+    private readonly opts;
+    private readonly handles;
+    private remoteAssets;
+    constructor(tag: string, root: string, manifest: ReleaseManifest, opts: OpenOptions);
+    receipt(): Receipt;
+    plan(asset: string): AssetPlan;
+    has(asset: string): boolean;
+    path(asset: string): string;
+    fetch(...assets: string[]): Promise<LandedFile[]>;
+    private listed;
+    private fetchOne;
+    private record;
+    db(asset: string): Database;
+    schoolReader(): SchoolReaderChoice;
+    builders(): readonly IndexBuilder[];
+    index(name: string, o?: {
+        force?: boolean;
+    }): Promise<string>;
+    indexDb(name: string): Promise<Database>;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+export declare function land(raw: string, pub: {
+    name: string;
+    digest: string | null;
+}, plan: AssetPlan, dest: string, opts: Pick<OpenOptions, "strict" | "keepCompressed">, log: (line: string) => void): Promise<LandedFile>;
+export declare function openRelease(spec?: string | number, opts?: OpenOptions): Promise<Release>;
+export declare function openCached(tag: string, opts?: OpenOptions): Release | null;

package/dist/types/remote.d.ts

@@ -0,0 +1,16 @@
+export interface RemoteAsset {
+    name: string;
+    size: number;
+    digest: string | null;
+}
+export interface Remote {
+    readonly name: string;
+    tags(repo: string): Promise<string[]>;
+    assets(repo: string, tag: string): Promise<RemoteAsset[]>;
+    download(repo: string, tag: string, name: string, dest: string): Promise<void>;
+}
+export declare const ghRemote: Remote;
+export declare function httpsRemote(env?: Readonly<Record<string, string | undefined>>, fetchImpl?: typeof fetch): Remote;
+export declare function fallbackRemote(first: Remote, second: Remote): Remote;
+export declare function setRemote(r: Remote | null): Remote | null;
+export declare function defaultRemote(): Remote;

package/dist/types/results.d.ts

@@ -0,0 +1,82 @@
+import type { Release } from "./release.js";
+export declare const FEIS_LOCAL_ID_FLOOR = 17179869184;
+export interface ResultQuery {
+    dancer_id?: number;
+    feis?: string;
+    competition?: string;
+    school_id?: string;
+    year?: number;
+    limit?: number;
+}
+export interface ResultRow {
+    address: string;
+    competition: string;
+    event: string;
+    year: number | null;
+    tier: string;
+    title: string | null;
+    age: string | null;
+    category: string | null;
+    gender: string | null;
+    feis_level: number | null;
+    comp_no: string | null;
+    place: number | null;
+    place_printed: string;
+    competitors: number | null;
+    name_printed: string;
+    dancer_id: number | null;
+    dancer_scope: "per-release" | "stable" | null;
+    school_printed: string;
+    school_id: string | null;
+    yob: number | null;
+    qualifier: string | null;
+}
+export interface ResultAnswer {
+    tag: string;
+    db: string;
+    asked: ResultQuery;
+    rows: ResultRow[];
+    truncated: number;
+}
+export declare function queryResults(rel: Release, db: string, q: ResultQuery): ResultAnswer;
+export declare class ResultFinder {
+    private readonly rel;
+    constructor(rel: Release);
+    query(q: ResultQuery): Promise<ResultAnswer>;
+}
+export interface MajorEvent {
+    event: string;
+    years: number[];
+    competitions: number;
+    rows: number;
+}
+export interface MajorCompetition {
+    competition: string;
+    event: string;
+    year: number | null;
+    tier: string;
+    comp_no: string | null;
+    title: string | null;
+    age: string | null;
+    gender: string | null;
+    category: string | null;
+    competitors: number | null;
+    rows: number;
+}
+export declare class MajorsFinder {
+    private readonly rel;
+    constructor(rel: Release);
+    private db;
+    events(): Promise<{
+        tag: string;
+        events: MajorEvent[];
+    }>;
+    competitions(q: {
+        event: string;
+        year?: number;
+    }): Promise<{
+        tag: string;
+        competitions: MajorCompetition[];
+    }>;
+    results(q: ResultQuery): Promise<ResultAnswer>;
+}

package/dist/types/schools.d.ts

@@ -0,0 +1,42 @@
+import { type SchoolNameParser } from "@finbheara/domain/school";
+import type { IndexBuilder } from "./indexes.js";
+import type { Release } from "./release.js";
+export type SchoolRung = "id" | "redirect" | "print" | "sn3" | "realWords";
+export interface SchoolCandidate {
+    school_id: string;
+    display: string | null;
+    rows: number;
+    by: SchoolRung;
+    prints: string[];
+    regions: string[];
+    places: string[];
+}
+export interface SchoolAnswer {
+    tag: string;
+    asked: string;
+    arm: "unique" | "ambiguous" | "none";
+    candidates: SchoolCandidate[];
+    region?: {
+        asked: string;
+        narrowed: boolean;
+    };
+    redirected?: {
+        from: string;
+        to: string;
+    };
+    refused?: string;
+}
+export interface SchoolQuery {
+    region?: string;
+}
+export interface SchoolReaderChoice {
+    id: string;
+    reader: SchoolNameParser;
+}
+export declare const GENERIC_SCHOOL_READER: SchoolReaderChoice;
+export declare const schoolsIndex: IndexBuilder;
+export declare class SchoolResolver {
+    private readonly rel;
+    constructor(rel: Release);
+    resolve(asked: string, q?: SchoolQuery): Promise<SchoolAnswer>;
+}

package/dist/types/tag.d.ts

@@ -0,0 +1,24 @@
+export declare const ARCHIVE_TAG: RegExp;
+export interface ArchiveTag {
+    date: string;
+    cut?: number;
+    fraction?: number;
+}
+export declare function parseArchiveTag(tag: string): ArchiveTag | null;
+export declare function renderArchiveTag(t: ArchiveTag): string;
+export declare function cutOf(inputRelease: string | undefined): number | undefined;
+export declare function compareTagsNewestFirst(a: string, b: string): number;
+export type ReleaseSpec = {
+    kind: "latest";
+} | {
+    kind: "pinned";
+} | {
+    kind: "cut";
+    cut: number;
+    fraction: number;
+} | {
+    kind: "tag";
+    tag: string;
+};
+export declare function parseReleaseSpec(spec: string | number): ReleaseSpec | string;
+export declare function pickTag(tags: readonly string[], spec: ReleaseSpec): string | null;

package/package.json

@@ -1,6 +1,53 @@
 {
-  "name": "@finbheara/archive-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@finbheara/archive-client",
+	"version": "0.1.0",
+	"description": "Open a versioned release of an Irish dance results archive: download, verify, decompress and cache it by tag, keep the cache, and resolve feises and schools against it",
+	"keywords": ["irish-dance", "results", "release", "cache", "sqlite"],
+	"license": "MIT",
+	"author": "Finbheara Systems",
+	"type": "module",
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./tag": {
+			"types": "./dist/types/tag.d.ts",
+			"default": "./dist/tag.js"
+		},
+		"./config": {
+			"types": "./dist/types/config.d.ts",
+			"default": "./dist/config.js"
+		},
+		"./cli": {
+			"types": "./dist/types/cli.d.ts",
+			"default": "./dist/cli.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/types/index.d.ts",
+	"bin": {
+		"idq": "./dist/cli.js"
+	},
+	"files": ["dist/*.js", "dist/chunks/*.js", "dist/types/**/*.d.ts", "README.md", "LICENSE"],
+	"engines": {
+		"bun": ">=1.4.2"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun scripts/build.ts",
+		"guard": "bun ../../tools/checks/archive-client-tarball.ts",
+		"prepublishOnly": "bun scripts/build.ts && bun ../../tools/checks/archive-client-tarball.ts"
+	},
+	"dependencies": {
+		"@finbheara/domain": "0.47.0",
+		"@finbheara/names": "0.22.0"
+	},
+	"devDependencies": {
+		"typescript": "7.0.2"
+	}
+}