osu-stable-db 0.1.2 → 0.2.1

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
 
@@ -55,39 +55,35 @@ const collectionDatabase: CollectionDatabase = {
 const collectionBytes = writeCollectionDatabase(collectionDatabase)
 ```
 
-Main entry exports:
-
-- All public types and constants
-- readOsuDatabase and writeOsuDatabase
-- readCollectionDatabase and writeCollectionDatabase
-- readScoresDatabase and writeScoresDatabase
-
 ## 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:/osu!')
 
-await writeCollectionDatabaseFile(
-  'path/to/collection.db',
-  {
-    version: osuDatabase.version,
-    collections: [],
-  },
-)
-```
+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)
+
+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
 
@@ -104,14 +100,13 @@ This project is 100% AI-generated.
 
 Committed minimal fixtures live in [tests/files](tests/files).
 
-Large real-world local fixtures can be placed in:
+To run tests and local scripts against your real osu! installation, set this in [.env](.env):
 
-- [tests/files/local](tests/files/local)
-
-That directory is git-ignored. When those files are present, the test suite will:
+```dotenv
+OSU_STABLE_DIR=C:/osu!
+```
 
-- parse them
-- verify byte-for-byte round-trip for osu!.db, collection.db, and scores.db
+When OSU_STABLE_DIR is set, local validation reads your real database files and verifies 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:
 
@@ -134,7 +129,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 referenced by OSU_STABLE_DIR:
 
 - 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,12 +1,30 @@
-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;
+declare const OSU_STABLE_DIR_ENV_VAR = "OSU_STABLE_DIR";
+declare function getConfiguredOsuFolderPath(): string | null;
+declare function getConfiguredOsuFolder(): OsuFolder | null;
 declare function readOsuDatabaseFile(path: DatabaseFilePath): Promise<OsuDatabase>;
 declare function writeOsuDatabaseFile(path: DatabaseFilePath, database: OsuDatabase): Promise<void>;
 declare function readCollectionDatabaseFile(path: DatabaseFilePath): Promise<CollectionDatabase>;
 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, OSU_STABLE_DIR_ENV_VAR, OsuFolder, getConfiguredOsuFolder, getConfiguredOsuFolderPath, readCollectionDatabaseFile, readOsuDatabaseFile, readScoresDatabaseFile, writeCollectionDatabaseFile, writeOsuDatabaseFile, writeScoresDatabaseFile };

package/dist/node.mjs

@@ -1,6 +1,16 @@
-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
+const OSU_STABLE_DIR_ENV_VAR = "OSU_STABLE_DIR";
+function getConfiguredOsuFolderPath() {
+	const folderPath = process.env[OSU_STABLE_DIR_ENV_VAR]?.trim();
+	return folderPath === void 0 || folderPath.length === 0 ? null : folderPath;
+}
+function getConfiguredOsuFolder() {
+	const folderPath = getConfiguredOsuFolderPath();
+	return folderPath === null ? null : new OsuFolder(folderPath);
+}
 async function readOsuDatabaseFile(path) {
 	return readOsuDatabase(new Uint8Array(await readFile(path)));
 }
@@ -19,5 +29,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 { OSU_STABLE_DIR_ENV_VAR, OsuFolder, getConfiguredOsuFolder, getConfiguredOsuFolderPath, 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.1",
   "description": "TypeScript reader and writer for osu!stable database files.",
   "author": "zzzzv",
   "license": "MIT",
@@ -29,9 +29,9 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "local:inspect": "pnpm run build && node scripts/local-inspect.mjs",
-    "local:roundtrip": "pnpm run build && node scripts/local-roundtrip.mjs",
-    "test": "vitest",
+    "local:inspect": "pnpm run build && node --env-file=.env scripts/local-inspect.mjs",
+    "local:roundtrip": "pnpm run build && node --env-file=.env scripts/local-roundtrip.mjs",
+    "test": "node --env-file=.env ./node_modules/vitest/vitest.mjs",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "pnpm run build"
   },