osu-stable-db 0.1.2 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@ This library currently supports the latest database structure from version 20250
 - collection.db
 - scores.db
 
-The core binary and database logic is browser-compatible. A separate Node-only subpath is provided for direct file reads and writes.
+The core binary and database logic is browser-compatible. A separate Node-only subpath is provided for direct file reads, writes, and osu! folder helpers.
 
 ## Scope
 
@@ -64,30 +64,32 @@ Main entry exports:
 
 ## Node Usage
 
-Use the Node subpath when you want direct file reads and writes through node:fs/promises.
+Use the Node subpath when you want to work with a full osu! folder or with direct file reads and writes through node:fs/promises.
 
 ```ts
 import {
-  readOsuDatabaseFile,
-  writeCollectionDatabaseFile,
+  OsuFolder,
 } from 'osu-stable-db/node'
 
-const osuDatabase = await readOsuDatabaseFile('path/to/osu!.db')
+const osuFolder = new OsuFolder('C:/Games/osu!')
+const osuDatabase = await osuFolder.readOsuDatabase()
+const scoresDatabase = await osuFolder.readScoresDatabase()
 
-await writeCollectionDatabaseFile(
-  'path/to/collection.db',
-  {
-    version: osuDatabase.version,
-    collections: [],
-  },
-)
-```
+const newestBeatmap = osuDatabase.beatmaps.at(-1)
+const newestScore = scoresDatabase.beatmaps.at(-1)?.scores.at(-1)
+
+if (newestBeatmap !== undefined) {
+  const osuFilePath = osuFolder.getOsuFilePath(newestBeatmap)
+  console.log(osuFilePath)
+}
 
-Node subpath exports:
+if (newestScore !== undefined) {
+  const osrFilePath = osuFolder.getOsrFilePath(newestScore)
+  console.log(osrFilePath)
+}
+```
 
-- readOsuDatabaseFile and writeOsuDatabaseFile
-- readCollectionDatabaseFile and writeCollectionDatabaseFile
-- readScoresDatabaseFile and writeScoresDatabaseFile
+If you only need path-based file IO, the same subpath also exports helpers such as readOsuDatabaseFile, writeCollectionDatabaseFile, and writeScoresDatabaseFile.
 
 ## Types And Time Values
 
@@ -107,12 +109,21 @@ Committed minimal fixtures live in [tests/files](tests/files).
 Large real-world local fixtures can be placed in:
 
 - [tests/files/local](tests/files/local)
+- [tests/files/local/osu!](tests/files/local/osu!) via a directory link created by the package script below
 
 That directory is git-ignored. When those files are present, the test suite will:
 
 - parse them
 - verify byte-for-byte round-trip for osu!.db, collection.db, and scores.db
 
+To link your real local osu! folder into the workspace on Windows, run:
+
+```bash
+pnpm run local:link -- "C:\\path\\to\\osu!"
+```
+
+This creates [tests/files/local/osu!](tests/files/local/osu!) as a directory junction. Tests and local scripts now prefer databases from that linked folder, and fall back to [tests/files/local](tests/files/local) for the previous workflow.
+
 You can also generate a local inspection report for a specific beatmap identifier with:
 
 ```bash
@@ -134,7 +145,7 @@ pnpm run build
 
 ## Notes On Validation
 
-Local validation also passes against private real-world database files in [tests/files/local](tests/files/local):
+Local validation also passes against private real-world database files in [tests/files/local/osu!](tests/files/local/osu!):
 
 - osu!.db: 58,295,932 bytes, 72,038 beatmaps
 - collection.db: 195,402 bytes, 11 collections, 5,743 stored beatmap references

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as readCollectionDatabase, c as Grades, d as RankedStatuses, f as UserPermissions, i as writeOsuDatabase, l as MINIMUM_SUPPORTED_VERSION, n as writeScoresDatabase, o as writeCollectionDatabase, r as readOsuDatabase, s as GameplayModes, t as readScoresDatabase, u as Mods } from "./scores-D_f7sIP0.mjs";
+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 };

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { b as ScoresDatabase, m as OsuDatabase, n as CollectionDatabase } from "./types-DiZMN3fQ.mjs";
+import { b as ScoresDatabase, m as OsuDatabase, n as CollectionDatabase, t as BeatmapEntry, v as ScoreEntry } from "./types-DiZMN3fQ.mjs";
 
 //#region src/node.d.ts
 type DatabaseFilePath = string | URL;
@@ -8,5 +8,20 @@ declare function readCollectionDatabaseFile(path: DatabaseFilePath): Promise<Col
 declare function writeCollectionDatabaseFile(path: DatabaseFilePath, database: CollectionDatabase): Promise<void>;
 declare function readScoresDatabaseFile(path: DatabaseFilePath): Promise<ScoresDatabase>;
 declare function writeScoresDatabaseFile(path: DatabaseFilePath, database: ScoresDatabase): Promise<void>;
+declare class OsuFolder {
+  folderPath: string;
+  constructor(folderPath: string);
+  getOsuDatabasePath(): string;
+  getCollectionDatabasePath(): string;
+  getScoresDatabasePath(): string;
+  readOsuDatabase(): Promise<OsuDatabase>;
+  writeOsuDatabase(database: OsuDatabase): Promise<void>;
+  readCollectionDatabase(): Promise<CollectionDatabase>;
+  writeCollectionDatabase(database: CollectionDatabase): Promise<void>;
+  readScoresDatabase(): Promise<ScoresDatabase>;
+  writeScoresDatabase(database: ScoresDatabase): Promise<void>;
+  getOsuFilePath(beatmap: BeatmapEntry): string;
+  getOsrFilePath(score: ScoreEntry): string;
+}
 //#endregion
-export { DatabaseFilePath, readCollectionDatabaseFile, readOsuDatabaseFile, readScoresDatabaseFile, writeCollectionDatabaseFile, writeOsuDatabaseFile, writeScoresDatabaseFile };
+export { DatabaseFilePath, OsuFolder, readCollectionDatabaseFile, readOsuDatabaseFile, readScoresDatabaseFile, writeCollectionDatabaseFile, writeOsuDatabaseFile, writeScoresDatabaseFile };

package/dist/node.mjs

@@ -1,5 +1,6 @@
-import { a as readCollectionDatabase, i as writeOsuDatabase, n as writeScoresDatabase, o as writeCollectionDatabase, r as readOsuDatabase, t as readScoresDatabase } from "./scores-D_f7sIP0.mjs";
+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 { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 //#region src/node.ts
 async function readOsuDatabaseFile(path) {
 	return readOsuDatabase(new Uint8Array(await readFile(path)));
@@ -19,5 +20,46 @@ async function readScoresDatabaseFile(path) {
 async function writeScoresDatabaseFile(path, database) {
 	await writeFile(path, writeScoresDatabase(database));
 }
+var OsuFolder = class {
+	folderPath;
+	constructor(folderPath) {
+		this.folderPath = folderPath;
+	}
+	getOsuDatabasePath() {
+		return join(this.folderPath, "osu!.db");
+	}
+	getCollectionDatabasePath() {
+		return join(this.folderPath, "collection.db");
+	}
+	getScoresDatabasePath() {
+		return join(this.folderPath, "scores.db");
+	}
+	async readOsuDatabase() {
+		return readOsuDatabaseFile(this.getOsuDatabasePath());
+	}
+	async writeOsuDatabase(database) {
+		await writeOsuDatabaseFile(this.getOsuDatabasePath(), database);
+	}
+	async readCollectionDatabase() {
+		return readCollectionDatabaseFile(this.getCollectionDatabasePath());
+	}
+	async writeCollectionDatabase(database) {
+		await writeCollectionDatabaseFile(this.getCollectionDatabasePath(), database);
+	}
+	async readScoresDatabase() {
+		return readScoresDatabaseFile(this.getScoresDatabasePath());
+	}
+	async writeScoresDatabase(database) {
+		await writeScoresDatabaseFile(this.getScoresDatabasePath(), database);
+	}
+	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);
+	}
+	getOsrFilePath(score) {
+		if (score.beatmapMd5Hash === null) throw new Error("Score entry is missing beatmapMd5Hash");
+		return join(this.folderPath, "Data", "r", `${score.beatmapMd5Hash}-${dateTimeTicksToWindowsFileTimeTicks(score.replayTimestamp)}.osr`);
+	}
+};
 //#endregion
-export { readCollectionDatabaseFile, readOsuDatabaseFile, readScoresDatabaseFile, writeCollectionDatabaseFile, writeOsuDatabaseFile, writeScoresDatabaseFile };
+export { OsuFolder, readCollectionDatabaseFile, readOsuDatabaseFile, readScoresDatabaseFile, writeCollectionDatabaseFile, writeOsuDatabaseFile, writeScoresDatabaseFile };

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

@@ -352,8 +352,20 @@ function writeOsuDatabase(database) {
 	writer.writeInt32(database.userPermissions);
 	return writer.toUint8Array();
 }
+//#endregion
+//#region src/core/utils.ts
+const WINDOWS_FILE_TIME_EPOCH_DATE_TIME_TICKS = 504911232000000000n;
 Object.values(Mods).filter((value) => value !== Mods.None);
 /**
+* Converts .NET DateTime ticks to Windows FILETIME ticks.
+*
+* scores.db stores replay timestamps as .NET DateTime ticks, while replay
+* filenames under Data/r use FILETIME ticks starting at 1601-01-01.
+*/
+function dateTimeTicksToWindowsFileTimeTicks(ticks) {
+	return ticks - WINDOWS_FILE_TIME_EPOCH_DATE_TIME_TICKS;
+}
+/**
 * Tests whether all bits from a mod mask are present in the flags value.
 */
 function hasMod(flags, mod) {
@@ -466,4 +478,4 @@ function writeScoresDatabase(database) {
 	return writer.toUint8Array();
 }
 //#endregion
-export { readCollectionDatabase as a, Grades as c, RankedStatuses as d, UserPermissions as f, writeOsuDatabase as i, MINIMUM_SUPPORTED_VERSION as l, writeScoresDatabase as n, writeCollectionDatabase as o, readOsuDatabase as r, GameplayModes as s, readScoresDatabase as t, Mods as u };
+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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "osu-stable-db",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "TypeScript reader and writer for osu!stable database files.",
   "author": "zzzzv",
   "license": "MIT",
@@ -29,6 +29,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "local:link": "node scripts/local-link.mjs",
     "local:inspect": "pnpm run build && node scripts/local-inspect.mjs",
     "local:roundtrip": "pnpm run build && node scripts/local-roundtrip.mjs",
     "test": "vitest",