osu-stable-db 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# osu-stable-db
+
+TypeScript reader and writer for osu!stable database files.
+
+This library currently supports the latest database structure from version 20250107 onward for:
+
+- osu!.db
+- 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.
+
+## Scope
+
+- Supports only 20250107 and later database structures
+- Preserves null string semantics used by the stable database format
+- Uses bigint for 64-bit values such as DateTime ticks
+- Exposes byte-array database APIs from the main entry
+- Exposes direct file APIs from the ./node subpath
+
+Older stable database versions are intentionally out of scope.
+
+## Install
+
+```bash
+pnpm add osu-stable-db
+```
+
+## Browser Usage
+
+Use the main entry when you already have bytes in memory.
+
+```ts
+import {
+  readOsuDatabase,
+  writeCollectionDatabase,
+  type CollectionDatabase,
+} from 'osu-stable-db'
+
+const osuBytes: ArrayBuffer = bytesFromSomewhere
+const osuDatabase = readOsuDatabase(osuBytes)
+
+const collectionDatabase: CollectionDatabase = {
+  version: osuDatabase.version,
+  collections: [
+    {
+      name: 'Favorites',
+      beatmapMd5Hashes: ['d41d8cd98f00b204e9800998ecf8427e'],
+    },
+  ],
+}
+
+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.
+
+```ts
+import {
+  readOsuDatabaseFile,
+  writeCollectionDatabaseFile,
+} from 'osu-stable-db/node'
+
+const osuDatabase = await readOsuDatabaseFile('path/to/osu!.db')
+
+await writeCollectionDatabaseFile(
+  'path/to/collection.db',
+  {
+    version: osuDatabase.version,
+    collections: [],
+  },
+)
+```
+
+Node subpath exports:
+
+- readOsuDatabaseFile and writeOsuDatabaseFile
+- readCollectionDatabaseFile and writeCollectionDatabaseFile
+- readScoresDatabaseFile and writeScoresDatabaseFile
+
+## Types And Time Values
+
+- Date-like 64-bit values are exposed as DateTimeTicks, backed by bigint
+- Helper functions for DateTimeTicks and mod flags live in [src/core/utils.ts](src/core/utils.ts)
+
+JavaScript Date is not used as the storage type because it loses sub-millisecond tick precision.
+
+## AI Disclosure
+
+This project is 100% AI-generated.
+
+## Tests And Fixtures
+
+Committed minimal fixtures live in [tests/files](tests/files).
+
+Large real-world local fixtures can be placed in:
+
+- [tests/files/local](tests/files/local)
+
+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
+
+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
+pnpm install
+pnpm run typecheck
+pnpm test -- --run
+pnpm run build
+```
+
+## Notes On Validation
+
+Local validation also passes against private real-world database files in [tests/files/local](tests/files/local):
+
+- osu!.db: 58,295,932 bytes, 72,038 beatmaps
+- collection.db: 195,402 bytes, 11 collections, 5,743 stored beatmap references
+- scores.db: 3,714,272 bytes, 11,331 beatmap score groups, 26,481 scores
+
+Those local tests passed with parsing and byte-for-byte round-trip verification enabled.

package/dist/index.d.mts

@@ -0,0 +1,15 @@
+import { C as UserPermissionFlags, S as UserPermission, _ as ScoreAdditionalModInfo, a as GameplayMode, b as ScoresDatabase, c as Grades, d as Mod, f as ModFlags, g as RankedStatuses, h as RankedStatus, i as DateTimeTicks, l as IntFloatPair, m as OsuDatabase, n as CollectionDatabase, o as GameplayModes, p as Mods, r as CollectionEntry, s as Grade, t as BeatmapEntry, u as MINIMUM_SUPPORTED_VERSION, v as ScoreEntry, w as UserPermissions, x as TimingPoint, y as ScoresBeatmapEntry } from "./types-DiZMN3fQ.mjs";
+
+//#region src/db/collection.d.ts
+declare function readCollectionDatabase(input: ArrayBuffer | Uint8Array): CollectionDatabase;
+declare function writeCollectionDatabase(database: CollectionDatabase): Uint8Array;
+//#endregion
+//#region src/db/osu.d.ts
+declare function readOsuDatabase(input: ArrayBuffer | Uint8Array): OsuDatabase;
+declare function writeOsuDatabase(database: OsuDatabase): Uint8Array;
+//#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 };

package/dist/index.mjs

@@ -0,0 +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";
+export { GameplayModes, Grades, MINIMUM_SUPPORTED_VERSION, Mods, RankedStatuses, UserPermissions, readCollectionDatabase, readOsuDatabase, readScoresDatabase, writeCollectionDatabase, writeOsuDatabase, writeScoresDatabase };

package/dist/node.d.mts

@@ -0,0 +1,12 @@
+import { b as ScoresDatabase, m as OsuDatabase, n as CollectionDatabase } from "./types-DiZMN3fQ.mjs";
+
+//#region src/node.d.ts
+type DatabaseFilePath = string | URL;
+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>;
+//#endregion
+export { DatabaseFilePath, readCollectionDatabaseFile, readOsuDatabaseFile, readScoresDatabaseFile, writeCollectionDatabaseFile, writeOsuDatabaseFile, writeScoresDatabaseFile };

package/dist/node.mjs

@@ -0,0 +1,23 @@
+import { a as readCollectionDatabase, i as writeOsuDatabase, n as writeScoresDatabase, o as writeCollectionDatabase, r as readOsuDatabase, t as readScoresDatabase } from "./scores-7qsAMzUc.mjs";
+import { readFile, writeFile } from "node:fs/promises";
+//#region src/node.ts
+async function readOsuDatabaseFile(path) {
+	return readOsuDatabase(new Uint8Array(await readFile(path)));
+}
+async function writeOsuDatabaseFile(path, database) {
+	await writeFile(path, writeOsuDatabase(database));
+}
+async function readCollectionDatabaseFile(path) {
+	return readCollectionDatabase(new Uint8Array(await readFile(path)));
+}
+async function writeCollectionDatabaseFile(path, database) {
+	await writeFile(path, writeCollectionDatabase(database));
+}
+async function readScoresDatabaseFile(path) {
+	return readScoresDatabase(new Uint8Array(await readFile(path)));
+}
+async function writeScoresDatabaseFile(path, database) {
+	await writeFile(path, writeScoresDatabase(database));
+}
+//#endregion
+export { readCollectionDatabaseFile, readOsuDatabaseFile, readScoresDatabaseFile, writeCollectionDatabaseFile, writeOsuDatabaseFile, writeScoresDatabaseFile };