osu-stable-db 0.1.1 → 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-7qsAMzUc.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-7qsAMzUc.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-7qsAMzUc.mjs → scores-C35i3lk0.mjs}

@@ -1,3 +1,4 @@
+import { BinaryReader, BinaryWriter } from "osu-binary";
 //#region src/types.ts
 /**
 * The minimum legacy database version supported by this library.
@@ -98,108 +99,10 @@ const Mods = {
 };
 //#endregion
 //#region src/core/binary.ts
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
-function toUint8Array(input) {
-	return input instanceof Uint8Array ? input : new Uint8Array(input);
-}
-var BinaryReader = class {
-	bytes;
-	view;
-	offset = 0;
-	constructor(input) {
-		this.bytes = toUint8Array(input);
-		this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength);
-	}
-	get position() {
-		return this.offset;
-	}
-	get length() {
-		return this.bytes.byteLength;
-	}
-	get remaining() {
-		return this.length - this.offset;
-	}
-	readByte() {
-		this.ensureAvailable(1);
-		const value = this.view.getUint8(this.offset);
-		this.offset += 1;
-		return value;
-	}
-	readBoolean() {
-		return this.readByte() !== 0;
-	}
-	readInt16() {
-		this.ensureAvailable(2);
-		const value = this.view.getInt16(this.offset, true);
-		this.offset += 2;
-		return value;
-	}
-	readUInt16() {
-		this.ensureAvailable(2);
-		const value = this.view.getUint16(this.offset, true);
-		this.offset += 2;
-		return value;
-	}
-	readInt32() {
-		this.ensureAvailable(4);
-		const value = this.view.getInt32(this.offset, true);
-		this.offset += 4;
-		return value;
-	}
-	readUInt32() {
-		this.ensureAvailable(4);
-		const value = this.view.getUint32(this.offset, true);
-		this.offset += 4;
-		return value;
-	}
-	readInt64() {
-		this.ensureAvailable(8);
-		const value = this.view.getBigInt64(this.offset, true);
-		this.offset += 8;
-		return value;
-	}
-	readSingle() {
-		this.ensureAvailable(4);
-		const value = this.view.getFloat32(this.offset, true);
-		this.offset += 4;
-		return value;
-	}
-	readDouble() {
-		this.ensureAvailable(8);
-		const value = this.view.getFloat64(this.offset, true);
-		this.offset += 8;
-		return value;
-	}
+var BinaryReader$1 = class extends BinaryReader {
 	readDateTimeTicks() {
 		return this.readInt64();
 	}
-	readBytes(length) {
-		if (!Number.isInteger(length) || length < 0) throw new RangeError(`Byte length must be a non-negative integer, got ${length}.`);
-		this.ensureAvailable(length);
-		const value = this.bytes.slice(this.offset, this.offset + length);
-		this.offset += length;
-		return value;
-	}
-	readUleb128() {
-		let value = 0;
-		let shift = 0;
-		while (true) {
-			const byte = this.readByte();
-			value |= (byte & 127) << shift;
-			if ((byte & 128) === 0) return value;
-			shift += 7;
-			if (shift > 35) throw new RangeError("ULEB128 value is too large for a JavaScript number.");
-		}
-	}
-	readString() {
-		const marker = this.readByte();
-		if (marker === 0) return null;
-		if (marker !== 11) throw new Error(`Invalid string marker 0x${marker.toString(16)}.`);
-		const length = this.readUleb128();
-		const value = this.readBytes(length);
-		return textDecoder.decode(value);
-	}
 	readIntFloatPair() {
 		const intMarker = this.readByte();
 		if (intMarker !== 8) throw new Error(`Invalid Int-Float pair int marker 0x${intMarker.toString(16)}.`);
@@ -218,95 +121,11 @@ var BinaryReader = class {
 			isUninherited: this.readBoolean()
 		};
 	}
-	ensureAvailable(byteLength) {
-		if (this.offset + byteLength > this.length) throw new RangeError(`Attempted to read ${byteLength} byte(s) at offset ${this.offset}, but only ${this.remaining} remain.`);
-	}
 };
-var BinaryWriter = class {
-	buffer;
-	view;
-	bytes;
-	offset = 0;
-	constructor(initialCapacity = 64) {
-		if (!Number.isInteger(initialCapacity) || initialCapacity <= 0) throw new RangeError(`Initial capacity must be a positive integer, got ${initialCapacity}.`);
-		this.buffer = new ArrayBuffer(initialCapacity);
-		this.view = new DataView(this.buffer);
-		this.bytes = new Uint8Array(this.buffer);
-	}
-	get position() {
-		return this.offset;
-	}
-	writeByte(value) {
-		this.ensureCapacity(1);
-		this.view.setUint8(this.offset, value);
-		this.offset += 1;
-	}
-	writeBoolean(value) {
-		this.writeByte(value ? 1 : 0);
-	}
-	writeInt16(value) {
-		this.ensureCapacity(2);
-		this.view.setInt16(this.offset, value, true);
-		this.offset += 2;
-	}
-	writeUInt16(value) {
-		this.ensureCapacity(2);
-		this.view.setUint16(this.offset, value, true);
-		this.offset += 2;
-	}
-	writeInt32(value) {
-		this.ensureCapacity(4);
-		this.view.setInt32(this.offset, value, true);
-		this.offset += 4;
-	}
-	writeUInt32(value) {
-		this.ensureCapacity(4);
-		this.view.setUint32(this.offset, value, true);
-		this.offset += 4;
-	}
-	writeInt64(value) {
-		this.ensureCapacity(8);
-		this.view.setBigInt64(this.offset, value, true);
-		this.offset += 8;
-	}
-	writeSingle(value) {
-		this.ensureCapacity(4);
-		this.view.setFloat32(this.offset, value, true);
-		this.offset += 4;
-	}
-	writeDouble(value) {
-		this.ensureCapacity(8);
-		this.view.setFloat64(this.offset, value, true);
-		this.offset += 8;
-	}
+var BinaryWriter$1 = class extends BinaryWriter {
 	writeDateTimeTicks(value) {
 		this.writeInt64(value);
 	}
-	writeBytes(value) {
-		this.ensureCapacity(value.byteLength);
-		this.bytes.set(value, this.offset);
-		this.offset += value.byteLength;
-	}
-	writeUleb128(value) {
-		if (!Number.isInteger(value) || value < 0) throw new RangeError(`ULEB128 value must be a non-negative integer, got ${value}.`);
-		let remaining = value;
-		do {
-			let byte = remaining & 127;
-			remaining >>>= 7;
-			if (remaining !== 0) byte |= 128;
-			this.writeByte(byte);
-		} while (remaining !== 0);
-	}
-	writeString(value) {
-		if (value === null) {
-			this.writeByte(0);
-			return;
-		}
-		this.writeByte(11);
-		const encoded = textEncoder.encode(value);
-		this.writeUleb128(encoded.byteLength);
-		this.writeBytes(encoded);
-	}
 	writeIntFloatPair(value) {
 		this.writeByte(8);
 		this.writeInt32(value.mods);
@@ -318,29 +137,14 @@ var BinaryWriter = class {
 		this.writeDouble(value.offsetMs);
 		this.writeBoolean(value.isUninherited);
 	}
-	toUint8Array() {
-		return this.bytes.slice(0, this.offset);
-	}
-	ensureCapacity(additionalBytes) {
-		const required = this.offset + additionalBytes;
-		if (required <= this.buffer.byteLength) return;
-		let nextCapacity = this.buffer.byteLength;
-		while (nextCapacity < required) nextCapacity *= 2;
-		const nextBuffer = new ArrayBuffer(nextCapacity);
-		const nextBytes = new Uint8Array(nextBuffer);
-		nextBytes.set(this.bytes.subarray(0, this.offset));
-		this.buffer = nextBuffer;
-		this.bytes = nextBytes;
-		this.view = new DataView(nextBuffer);
-	}
 };
 //#endregion
 //#region src/db/shared.ts
 function createReader(input) {
-	return new BinaryReader(input);
+	return new BinaryReader$1(input);
 }
 function createWriter() {
-	return new BinaryWriter();
+	return new BinaryWriter$1();
 }
 function assertSupportedVersion(version) {
 	if (version < 20250107) throw new RangeError(`Unsupported legacy database version ${version}. Minimum supported version is ${MINIMUM_SUPPORTED_VERSION}.`);
@@ -548,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) {
@@ -662,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.1",
+  "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",
@@ -41,5 +42,8 @@
     "tsdown": "^0.21.7",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"
+  },
+  "dependencies": {
+    "osu-binary": "^0.1.0"
   }
 }