osu-stable-db 0.2.2 → 0.2.3

package/README.md

@@ -69,22 +69,46 @@ const osuFolder = new OsuFolder('C:/osu!')
 const osuDatabase = await osuFolder.readOsuDatabase()
 const scoresDatabase = await osuFolder.readScoresDatabase()
 
-const newestBeatmap = osuDatabase.beatmaps.at(-1)
-const newestScore = scoresDatabase.beatmaps.at(-1)?.scores.at(-1)
+const query = osuFolder.createBeatmapScoreQuery(osuDatabase, scoresDatabase)
 
-if (newestBeatmap !== undefined) {
-  const osuFilePath = osuFolder.getOsuFilePath(newestBeatmap)
-  console.log(osuFilePath)
-}
-
-if (newestScore !== undefined) {
-  const osrFilePath = osuFolder.getOsrFilePath(newestScore)
-  console.log(osrFilePath)
+for (const { beatmap, score } of query.iterateBeatmapScores()) {
+  console.log(beatmap.getOsuFilePath())
+  console.log(score.getOsrFilePath())
 }
 ```
 
 If you only need path-based file IO, the same subpath also exports helpers such as readOsuDatabaseFile, writeCollectionDatabaseFile, and writeScoresDatabaseFile.
 
+## Query Helpers
+
+Use createBeatmapScoreQuery when you want to join osu!.db beatmaps with scores.db entries by beatmap MD5 hash.
+
+It accepts either full database objects or the underlying beatmap and score-group arrays, and returns two generators:
+
+- iterateBeatmapScoreGroups yields one beatmap with its matching ScoreEntry array
+- iterateBeatmapScores yields one beatmap with one flattened ScoreEntry at a time
+
+```ts
+import {
+  createBeatmapScoreQuery,
+  readOsuDatabase,
+  readScoresDatabase,
+} from 'osu-stable-db'
+
+const osuDatabase = readOsuDatabase(osuBytes)
+const scoresDatabase = readScoresDatabase(scoresBytes)
+
+const query = createBeatmapScoreQuery(osuDatabase, scoresDatabase)
+
+for (const { beatmap, scores } of query.iterateBeatmapScoreGroups()) {
+  console.log(beatmap.beatmapId, scores.length)
+}
+
+for (const { beatmap, score } of query.iterateBeatmapScores()) {
+  console.log(beatmap.difficultyName, score.playerName, score.totalScore)
+}
+```
+
 ## Types And Time Values
 
 - Date-like 64-bit values are exposed as DateTimeTicks, backed by bigint
@@ -100,7 +124,7 @@ This project is 100% AI-generated.
 
 Committed minimal fixtures live in [tests/files](tests/files).
 
-To run local node tests and the inspection script against your real osu! installation, set this in [.env](.env):
+To run local node tests against your real osu! installation, set this in [.env](.env):
 
 ```dotenv
 OSU_STABLE_DIR=C:/osu!
@@ -108,16 +132,6 @@ OSU_STABLE_DIR=C:/osu!
 
 When OSU_STABLE_DIR is set, local node tests read your real database files and verify byte-for-byte round-trip for osu!.db, collection.db, and scores.db.
 
-You can also generate a local inspection report for a specific beatmap identifier with:
-
-```bash
-pnpm run local:inspect -- 5288868
-```
-
-The generated report is written to:
-
-- [tests/files/local/reports](tests/files/local/reports)
-
 ## Development
 
 ```bash

package/dist/index.d.mts

@@ -8,8 +8,24 @@ declare function writeCollectionDatabase(database: CollectionDatabase): Uint8Arr
 declare function readOsuDatabase(input: ArrayBuffer | Uint8Array): OsuDatabase;
 declare function writeOsuDatabase(database: OsuDatabase): Uint8Array;
 //#endregion
+//#region src/db/query.d.ts
+interface BeatmapScoresGroupMatch {
+  beatmap: BeatmapEntry;
+  scores: ScoreEntry[];
+}
+interface BeatmapScoreMatch {
+  beatmap: BeatmapEntry;
+  score: ScoreEntry;
+}
+type BeatmapQuerySource = OsuDatabase | BeatmapEntry[];
+type ScoreQuerySource = ScoresDatabase | ScoresBeatmapEntry[];
+declare function createBeatmapScoreQuery(beatmapsSource: BeatmapQuerySource, scoresSource: ScoreQuerySource): {
+  iterateBeatmapScoreGroups: () => Generator<BeatmapScoresGroupMatch>;
+  iterateBeatmapScores: () => Generator<BeatmapScoreMatch>;
+};
+//#endregion
 //#region src/db/scores.d.ts
 declare function readScoresDatabase(input: ArrayBuffer | Uint8Array): ScoresDatabase;
 declare function writeScoresDatabase(database: ScoresDatabase): Uint8Array;
 //#endregion
-export { BeatmapEntry, CollectionDatabase, CollectionEntry, DateTimeTicks, GameplayMode, GameplayModes, Grade, Grades, IntFloatPair, MINIMUM_SUPPORTED_VERSION, Mod, ModFlags, Mods, OsuDatabase, RankedStatus, RankedStatuses, ScoreAdditionalModInfo, ScoreEntry, ScoresBeatmapEntry, ScoresDatabase, TimingPoint, UserPermission, UserPermissionFlags, UserPermissions, readCollectionDatabase, readOsuDatabase, readScoresDatabase, writeCollectionDatabase, writeOsuDatabase, writeScoresDatabase };
+export { BeatmapEntry, BeatmapQuerySource, BeatmapScoreMatch, BeatmapScoresGroupMatch, CollectionDatabase, CollectionEntry, DateTimeTicks, GameplayMode, GameplayModes, Grade, Grades, IntFloatPair, MINIMUM_SUPPORTED_VERSION, Mod, ModFlags, Mods, OsuDatabase, RankedStatus, RankedStatuses, ScoreAdditionalModInfo, ScoreEntry, ScoreQuerySource, ScoresBeatmapEntry, ScoresDatabase, TimingPoint, UserPermission, UserPermissionFlags, UserPermissions, createBeatmapScoreQuery, readCollectionDatabase, readOsuDatabase, readScoresDatabase, writeCollectionDatabase, writeOsuDatabase, writeScoresDatabase };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as writeOsuDatabase, c as GameplayModes, d as Mods, f as RankedStatuses, i as readOsuDatabase, l as Grades, n as writeScoresDatabase, o as readCollectionDatabase, p as UserPermissions, s as writeCollectionDatabase, t as readScoresDatabase, u as MINIMUM_SUPPORTED_VERSION } from "./scores-C35i3lk0.mjs";
-export { GameplayModes, Grades, MINIMUM_SUPPORTED_VERSION, Mods, RankedStatuses, UserPermissions, readCollectionDatabase, readOsuDatabase, readScoresDatabase, writeCollectionDatabase, writeOsuDatabase, writeScoresDatabase };
+import { a as readOsuDatabase, c as writeCollectionDatabase, d as MINIMUM_SUPPORTED_VERSION, f as Mods, i as createBeatmapScoreQuery, l as GameplayModes, m as UserPermissions, n as writeScoresDatabase, o as writeOsuDatabase, p as RankedStatuses, s as readCollectionDatabase, t as readScoresDatabase, u as Grades } from "./scores-CW2CUXZ-.mjs";
+export { GameplayModes, Grades, MINIMUM_SUPPORTED_VERSION, Mods, RankedStatuses, UserPermissions, createBeatmapScoreQuery, readCollectionDatabase, readOsuDatabase, readScoresDatabase, writeCollectionDatabase, writeOsuDatabase, writeScoresDatabase };

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { b as ScoresDatabase, m as OsuDatabase, n as CollectionDatabase, t as BeatmapEntry, v as ScoreEntry } from "./types-DiZMN3fQ.mjs";
+import { _ as ScoreAdditionalModInfo, a as GameplayMode, b as ScoresDatabase, f as ModFlags, h as RankedStatus, i as DateTimeTicks, l as IntFloatPair, m as OsuDatabase, n as CollectionDatabase, s as Grade, t as BeatmapEntry, v as ScoreEntry, x as TimingPoint } from "./types-DiZMN3fQ.mjs";
 
 //#region src/node.d.ts
 type DatabaseFilePath = string | URL;
@@ -23,6 +23,173 @@ declare class OsuFolder {
   writeCollectionDatabase(database: CollectionDatabase): Promise<void>;
   readScoresDatabase(): Promise<ScoresDatabase>;
   writeScoresDatabase(database: ScoresDatabase): Promise<void>;
+  createBeatmapScoreQuery(beatmapsSource: OsuDatabase | BeatmapEntry[], scoresSource: ScoresDatabase | Array<{
+    beatmapMd5Hash: string | null;
+    scores: ScoreEntry[];
+  }>): {
+    iterateBeatmapScoreGroups: () => Generator<{
+      beatmap: {
+        artist: string | null;
+        artistUnicode: string | null;
+        title: string | null;
+        titleUnicode: string | null;
+        creator: string | null;
+        difficultyName: string | null;
+        audioFileName: string | null;
+        md5Hash: string | null;
+        osuFileName: string | null;
+        rankedStatus: RankedStatus;
+        hitCircleCount: number;
+        sliderCount: number;
+        spinnerCount: number;
+        lastModificationTime: DateTimeTicks;
+        approachRate: number;
+        circleSize: number;
+        hpDrain: number;
+        overallDifficulty: number;
+        sliderVelocity: number;
+        standardStarRatings: IntFloatPair[];
+        taikoStarRatings: IntFloatPair[];
+        catchStarRatings: IntFloatPair[];
+        maniaStarRatings: IntFloatPair[];
+        drainTimeSeconds: number;
+        totalTimeMs: number;
+        previewOffsetMs: number;
+        timingPoints: TimingPoint[];
+        difficultyId: number;
+        beatmapId: number;
+        threadId: number;
+        standardGrade: Grade;
+        taikoGrade: Grade;
+        catchGrade: Grade;
+        maniaGrade: Grade;
+        localOffset: number;
+        stackLeniency: number;
+        gameplayMode: GameplayMode;
+        source: string | null;
+        tags: string | null;
+        onlineOffset: number;
+        titleFont: string | null;
+        isUnplayed: boolean;
+        lastPlayedAt: DateTimeTicks;
+        isOsz2: boolean;
+        beatmapFolderName: string | null;
+        lastCheckedAgainstRepositoryAt: DateTimeTicks;
+        ignoreBeatmapSound: boolean;
+        ignoreBeatmapSkin: boolean;
+        disableStoryboard: boolean;
+        disableVideo: boolean;
+        visualOverride: boolean;
+        lastModificationTimeUnknown: number;
+        maniaScrollSpeed: number;
+        getOsuFilePath: () => string;
+      };
+      scores: {
+        gameplayMode: GameplayMode;
+        version: number;
+        beatmapMd5Hash: string | null;
+        playerName: string | null;
+        replayMd5Hash: string | null;
+        count300: number;
+        count100: number;
+        count50: number;
+        countGeki: number;
+        countKatu: number;
+        countMiss: number;
+        totalScore: number;
+        maxCombo: number;
+        perfectCombo: boolean;
+        mods: ModFlags;
+        reservedEmptyString: string | null;
+        replayTimestamp: DateTimeTicks;
+        reservedInt32: number;
+        onlineScoreId: bigint;
+        additionalModInfo?: ScoreAdditionalModInfo;
+        getOsrFilePath: () => string;
+      }[];
+    }, void, unknown>;
+    iterateBeatmapScores: () => Generator<{
+      beatmap: {
+        artist: string | null;
+        artistUnicode: string | null;
+        title: string | null;
+        titleUnicode: string | null;
+        creator: string | null;
+        difficultyName: string | null;
+        audioFileName: string | null;
+        md5Hash: string | null;
+        osuFileName: string | null;
+        rankedStatus: RankedStatus;
+        hitCircleCount: number;
+        sliderCount: number;
+        spinnerCount: number;
+        lastModificationTime: DateTimeTicks;
+        approachRate: number;
+        circleSize: number;
+        hpDrain: number;
+        overallDifficulty: number;
+        sliderVelocity: number;
+        standardStarRatings: IntFloatPair[];
+        taikoStarRatings: IntFloatPair[];
+        catchStarRatings: IntFloatPair[];
+        maniaStarRatings: IntFloatPair[];
+        drainTimeSeconds: number;
+        totalTimeMs: number;
+        previewOffsetMs: number;
+        timingPoints: TimingPoint[];
+        difficultyId: number;
+        beatmapId: number;
+        threadId: number;
+        standardGrade: Grade;
+        taikoGrade: Grade;
+        catchGrade: Grade;
+        maniaGrade: Grade;
+        localOffset: number;
+        stackLeniency: number;
+        gameplayMode: GameplayMode;
+        source: string | null;
+        tags: string | null;
+        onlineOffset: number;
+        titleFont: string | null;
+        isUnplayed: boolean;
+        lastPlayedAt: DateTimeTicks;
+        isOsz2: boolean;
+        beatmapFolderName: string | null;
+        lastCheckedAgainstRepositoryAt: DateTimeTicks;
+        ignoreBeatmapSound: boolean;
+        ignoreBeatmapSkin: boolean;
+        disableStoryboard: boolean;
+        disableVideo: boolean;
+        visualOverride: boolean;
+        lastModificationTimeUnknown: number;
+        maniaScrollSpeed: number;
+        getOsuFilePath: () => string;
+      };
+      score: {
+        gameplayMode: GameplayMode;
+        version: number;
+        beatmapMd5Hash: string | null;
+        playerName: string | null;
+        replayMd5Hash: string | null;
+        count300: number;
+        count100: number;
+        count50: number;
+        countGeki: number;
+        countKatu: number;
+        countMiss: number;
+        totalScore: number;
+        maxCombo: number;
+        perfectCombo: boolean;
+        mods: ModFlags;
+        reservedEmptyString: string | null;
+        replayTimestamp: DateTimeTicks;
+        reservedInt32: number;
+        onlineScoreId: bigint;
+        additionalModInfo?: ScoreAdditionalModInfo;
+        getOsrFilePath: () => string;
+      };
+    }, void, unknown>;
+  };
   getOsuFilePath(beatmap: BeatmapEntry): string;
   getOsrFilePath(score: ScoreEntry): string;
 }

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { a as writeOsuDatabase, i as readOsuDatabase, n as writeScoresDatabase, o as readCollectionDatabase, r as dateTimeTicksToWindowsFileTimeTicks, s as writeCollectionDatabase, t as readScoresDatabase } from "./scores-C35i3lk0.mjs";
+import { a as readOsuDatabase, c as writeCollectionDatabase, i as createBeatmapScoreQuery, n as writeScoresDatabase, o as writeOsuDatabase, r as dateTimeTicksToWindowsFileTimeTicks, s as readCollectionDatabase, t as readScoresDatabase } from "./scores-CW2CUXZ-.mjs";
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/node.ts
@@ -61,6 +61,35 @@ var OsuFolder = class {
 	async writeScoresDatabase(database) {
 		await writeScoresDatabaseFile(this.getScoresDatabasePath(), database);
 	}
+	createBeatmapScoreQuery(beatmapsSource, scoresSource) {
+		const query = createBeatmapScoreQuery(beatmapsSource, scoresSource);
+		const wrapBeatmap = (beatmap) => ({
+			...beatmap,
+			getOsuFilePath: () => this.getOsuFilePath(beatmap)
+		});
+		const wrapScore = (score) => ({
+			...score,
+			getOsrFilePath: () => this.getOsrFilePath(score)
+		});
+		const wrapBeatmapScoresGroupMatch = ({ beatmap, scores }) => ({
+			beatmap: wrapBeatmap(beatmap),
+			scores: scores.map(wrapScore)
+		});
+		const wrapBeatmapScoreMatch = ({ beatmap, score }) => ({
+			beatmap: wrapBeatmap(beatmap),
+			score: wrapScore(score)
+		});
+		function* iterateBeatmapScoreGroups() {
+			for (const match of query.iterateBeatmapScoreGroups()) yield wrapBeatmapScoresGroupMatch(match);
+		}
+		function* iterateBeatmapScores() {
+			for (const match of query.iterateBeatmapScores()) yield wrapBeatmapScoreMatch(match);
+		}
+		return {
+			iterateBeatmapScoreGroups,
+			iterateBeatmapScores
+		};
+	}
 	getOsuFilePath(beatmap) {
 		if (beatmap.beatmapFolderName === null || beatmap.osuFileName === null) throw new Error("Beatmap entry is missing beatmapFolderName or osuFileName");
 		return join(this.folderPath, "Songs", beatmap.beatmapFolderName, beatmap.osuFileName);

package/dist/{scores-C35i3lk0.mjs → scores-CW2CUXZ-.mjs}

@@ -353,6 +353,40 @@ function writeOsuDatabase(database) {
 	return writer.toUint8Array();
 }
 //#endregion
+//#region src/db/query.ts
+function getBeatmapEntries(source) {
+	return Array.isArray(source) ? source : source.beatmaps;
+}
+function getScoreEntries(source) {
+	return Array.isArray(source) ? source : source.beatmaps;
+}
+function createBeatmapScoreQuery(beatmapsSource, scoresSource) {
+	const beatmaps = getBeatmapEntries(beatmapsSource);
+	const scoreGroups = getScoreEntries(scoresSource);
+	const beatmapByMd5Hash = /* @__PURE__ */ new Map();
+	for (const beatmap of beatmaps) if (beatmap.md5Hash !== null) beatmapByMd5Hash.set(beatmap.md5Hash, beatmap);
+	function* iterateBeatmapScoreGroups() {
+		for (const scoreGroup of scoreGroups) {
+			if (scoreGroup.beatmapMd5Hash === null) continue;
+			const beatmap = beatmapByMd5Hash.get(scoreGroup.beatmapMd5Hash);
+			if (beatmap !== void 0) yield {
+				beatmap,
+				scores: scoreGroup.scores
+			};
+		}
+	}
+	function* iterateBeatmapScores() {
+		for (const { beatmap, scores } of iterateBeatmapScoreGroups()) for (const score of scores) yield {
+			beatmap,
+			score
+		};
+	}
+	return {
+		iterateBeatmapScoreGroups,
+		iterateBeatmapScores
+	};
+}
+//#endregion
 //#region src/core/utils.ts
 const WINDOWS_FILE_TIME_EPOCH_DATE_TIME_TICKS = 504911232000000000n;
 Object.values(Mods).filter((value) => value !== Mods.None);
@@ -478,4 +512,4 @@ function writeScoresDatabase(database) {
 	return writer.toUint8Array();
 }
 //#endregion
-export { writeOsuDatabase as a, GameplayModes as c, Mods as d, RankedStatuses as f, readOsuDatabase as i, Grades as l, writeScoresDatabase as n, readCollectionDatabase as o, UserPermissions as p, dateTimeTicksToWindowsFileTimeTicks as r, writeCollectionDatabase as s, readScoresDatabase as t, MINIMUM_SUPPORTED_VERSION as u };
+export { readOsuDatabase as a, writeCollectionDatabase as c, MINIMUM_SUPPORTED_VERSION as d, Mods as f, createBeatmapScoreQuery as i, GameplayModes as l, UserPermissions as m, writeScoresDatabase as n, writeOsuDatabase as o, RankedStatuses as p, dateTimeTicksToWindowsFileTimeTicks as r, readCollectionDatabase as s, readScoresDatabase as t, Grades as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "osu-stable-db",
   "type": "module",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "TypeScript reader and writer for osu!stable database files.",
   "author": "zzzzv",
   "license": "MIT",