osu-stable-db 0.1.0

package/dist/types-DiZMN3fQ.d.mts

@@ -0,0 +1,547 @@
+//#region src/types.d.ts
+/**
+ * The minimum legacy database version supported by this library.
+ *
+ * Only the latest stable structure introduced in version 20250107 is modeled.
+ */
+declare const MINIMUM_SUPPORTED_VERSION = 20250107;
+/**
+ * Legacy gameplay mode identifiers used by osu!stable database files.
+ */
+declare const GameplayModes: {
+  readonly Osu: 0;
+  readonly Taiko: 1;
+  readonly Catch: 2;
+  readonly Mania: 3;
+};
+/**
+ * Beatmap ranked status values stored in osu!.db.
+ */
+declare const RankedStatuses: {
+  readonly Unknown: 0;
+  readonly Unsubmitted: 1;
+  readonly Pending: 2;
+  readonly Unused: 3;
+  readonly Ranked: 4;
+  readonly Approved: 5;
+  readonly Qualified: 6;
+  readonly Loved: 7;
+};
+/**
+ * Grade values stored in osu!.db for each ruleset.
+ *
+ * This matches legacy stable grade byte values used by osu!.db.
+ */
+declare const Grades: {
+  readonly XH: 0;
+  readonly SH: 1;
+  readonly X: 2;
+  readonly S: 3;
+  readonly A: 4;
+  readonly B: 5;
+  readonly C: 6;
+  readonly D: 7;
+  readonly F: 8;
+  readonly N: 9;
+};
+/**
+ * User permission flags stored in osu!.db.
+ */
+declare const UserPermissions: {
+  readonly None: 0;
+  readonly Normal: 1;
+  readonly Moderator: 2;
+  readonly Supporter: 4;
+  readonly Friend: 8;
+  readonly Peppy: 16;
+  readonly WorldCupStaff: 32;
+};
+/**
+ * Legacy mod flags used by scores.db, osu!.db star ratings, and replay-derived data.
+ *
+ * This is a flag enum expressed as a const object. Values are intended to be combined
+ * with bitwise operations such as `Hidden | HardRock`.
+ */
+declare const Mods: {
+  readonly None: 0;
+  readonly NoFail: 1;
+  readonly Easy: 2;
+  readonly TouchDevice: 4;
+  readonly Hidden: 8;
+  readonly HardRock: 16;
+  readonly SuddenDeath: 32;
+  readonly DoubleTime: 64;
+  readonly Relax: 128;
+  readonly HalfTime: 256;
+  readonly Nightcore: 512;
+  readonly Flashlight: 1024;
+  readonly Autoplay: 2048;
+  readonly SpunOut: 4096;
+  readonly Autopilot: 8192;
+  readonly Perfect: 16384;
+  readonly Key4: 32768;
+  readonly Key5: 65536;
+  readonly Key6: 131072;
+  readonly Key7: 262144;
+  readonly Key8: 524288;
+  readonly FadeIn: 1048576;
+  readonly Random: 2097152;
+  readonly Cinema: 4194304;
+  readonly TargetPractice: 8388608;
+  readonly Key9: 16777216;
+  readonly KeyCoop: 33554432;
+  readonly Key1: 67108864;
+  readonly Key3: 134217728;
+  readonly Key2: 268435456;
+  readonly ScoreV2: 536870912;
+  readonly Mirror: 1073741824;
+};
+type GameplayMode = (typeof GameplayModes)[keyof typeof GameplayModes];
+type RankedStatus = (typeof RankedStatuses)[keyof typeof RankedStatuses];
+type Grade = (typeof Grades)[keyof typeof Grades];
+type UserPermission = (typeof UserPermissions)[keyof typeof UserPermissions];
+type UserPermissionFlags = number;
+type Mod = (typeof Mods)[keyof typeof Mods];
+type ModFlags = number;
+/**
+ * A 64-bit .NET DateTime ticks value.
+ *
+ * One tick is 100 nanoseconds since 0001-01-01T00:00:00Z.
+ *
+ * The legacy database wiki calls some timestamp fields "Windows ticks", but
+ * reference implementations decode the corresponding values as .NET DateTime
+ * ticks for unlock dates, beatmap timestamps, and replay timestamps.
+ */
+type DateTimeTicks = bigint;
+/**
+ * A pair of legacy mod flags and a star rating value.
+ */
+interface IntFloatPair {
+  /**
+   * Bitwise combination of mods for which this star rating was computed.
+   */
+  mods: ModFlags;
+  /**
+   * Star rating value stored as a 32-bit float in version 20250107 and later.
+   */
+  starRating: number;
+}
+/**
+ * A timing point entry stored inside a beatmap entry in osu!.db.
+ */
+interface TimingPoint {
+  /**
+   * BPM value stored by the database.
+   */
+  bpm: number;
+  /**
+   * Offset into the song, in milliseconds.
+   */
+  offsetMs: number;
+  /**
+   * Raw timing-change flag.
+   *
+   * If false, the timing point is inherited.
+   */
+  isUninherited: boolean;
+}
+/**
+ * Beatmap metadata cached inside osu!.db.
+ */
+interface BeatmapEntry {
+  /**
+   * Artist name.
+   */
+  artist: string | null;
+  /**
+   * Artist name in Unicode.
+   */
+  artistUnicode: string | null;
+  /**
+   * Song title.
+   */
+  title: string | null;
+  /**
+   * Song title in Unicode.
+   */
+  titleUnicode: string | null;
+  /**
+   * Creator name.
+   */
+  creator: string | null;
+  /**
+   * Difficulty name such as Hard or Insane.
+   */
+  difficultyName: string | null;
+  /**
+   * Audio file name.
+   */
+  audioFileName: string | null;
+  /**
+   * MD5 hash of the beatmap.
+   */
+  md5Hash: string | null;
+  /**
+   * Name of the corresponding .osu file.
+   */
+  osuFileName: string | null;
+  /**
+   * Ranked status byte.
+   */
+  rankedStatus: RankedStatus;
+  /**
+   * Number of hitcircles.
+   */
+  hitCircleCount: number;
+  /**
+   * Number of sliders.
+   */
+  sliderCount: number;
+  /**
+   * Number of spinners.
+   */
+  spinnerCount: number;
+  /**
+   * Last modification time, in .NET DateTime ticks.
+   */
+  lastModificationTime: DateTimeTicks;
+  /**
+   * Approach rate.
+   */
+  approachRate: number;
+  /**
+   * Circle size.
+   */
+  circleSize: number;
+  /**
+   * HP drain.
+   */
+  hpDrain: number;
+  /**
+   * Overall difficulty.
+   */
+  overallDifficulty: number;
+  /**
+   * Slider velocity.
+   */
+  sliderVelocity: number;
+  /**
+   * Star rating info for osu!standard.
+   */
+  standardStarRatings: IntFloatPair[];
+  /**
+   * Star rating info for osu!taiko.
+   */
+  taikoStarRatings: IntFloatPair[];
+  /**
+   * Star rating info for osu!catch.
+   */
+  catchStarRatings: IntFloatPair[];
+  /**
+   * Star rating info for osu!mania.
+   */
+  maniaStarRatings: IntFloatPair[];
+  /**
+   * Drain time, in seconds.
+   */
+  drainTimeSeconds: number;
+  /**
+   * Total time, in milliseconds.
+   */
+  totalTimeMs: number;
+  /**
+   * Preview start time in beatmap select, in milliseconds.
+   */
+  previewOffsetMs: number;
+  /**
+   * Timing points attached to this beatmap.
+   */
+  timingPoints: TimingPoint[];
+  /**
+   * Online difficulty ID.
+   */
+  difficultyId: number;
+  /**
+   * Online beatmap ID.
+   */
+  beatmapId: number;
+  /**
+   * Online thread ID.
+   */
+  threadId: number;
+  /**
+   * Grade achieved in osu!standard.
+   */
+  standardGrade: Grade;
+  /**
+   * Grade achieved in osu!taiko.
+   */
+  taikoGrade: Grade;
+  /**
+   * Grade achieved in osu!catch.
+   */
+  catchGrade: Grade;
+  /**
+   * Grade achieved in osu!mania.
+   */
+  maniaGrade: Grade;
+  /**
+   * Local beatmap offset.
+   */
+  localOffset: number;
+  /**
+   * Stack leniency.
+   */
+  stackLeniency: number;
+  /**
+   * osu! gameplay mode.
+   */
+  gameplayMode: GameplayMode;
+  /**
+   * Song source.
+   */
+  source: string | null;
+  /**
+   * Song tags.
+   */
+  tags: string | null;
+  /**
+   * Online offset.
+   */
+  onlineOffset: number;
+  /**
+   * Font used for the song title.
+   */
+  titleFont: string | null;
+  /**
+   * Whether the beatmap is unplayed.
+   */
+  isUnplayed: boolean;
+  /**
+   * Last time the beatmap was played, in .NET DateTime ticks.
+   */
+  lastPlayedAt: DateTimeTicks;
+  /**
+   * Whether the beatmap is stored in osz2 format.
+   */
+  isOsz2: boolean;
+  /**
+   * Beatmap folder name relative to Songs.
+   */
+  beatmapFolderName: string | null;
+  /**
+   * Last time the beatmap was checked against the osu! repository, in .NET DateTime ticks.
+   */
+  lastCheckedAgainstRepositoryAt: DateTimeTicks;
+  /**
+   * Ignore beatmap sound.
+   */
+  ignoreBeatmapSound: boolean;
+  /**
+   * Ignore beatmap skin.
+   */
+  ignoreBeatmapSkin: boolean;
+  /**
+   * Disable storyboard.
+   */
+  disableStoryboard: boolean;
+  /**
+   * Disable video.
+   */
+  disableVideo: boolean;
+  /**
+   * Visual override.
+   */
+  visualOverride: boolean;
+  /**
+   * An unknown 32-bit integer documented as "Last modification time (?)".
+   */
+  lastModificationTimeUnknown: number;
+  /**
+   * Mania scroll speed.
+   */
+  maniaScrollSpeed: number;
+}
+/**
+ * Top-level structure of osu!.db for supported versions.
+ */
+interface OsuDatabase {
+  /**
+   * osu! version such as 20250107.
+   */
+  version: number;
+  /**
+   * Folder count.
+   */
+  folderCount: number;
+  /**
+   * AccountUnlocked. Only false when the account is locked or banned in any way.
+   */
+  accountUnlocked: boolean;
+  /**
+   * Date the account will be unlocked, in .NET DateTime ticks.
+   */
+  accountUnlockDate: DateTimeTicks;
+  /**
+   * Player name.
+   */
+  playerName: string | null;
+  /**
+   * Cached beatmaps.
+   */
+  beatmaps: BeatmapEntry[];
+  /**
+   * User permission flags.
+   */
+  userPermissions: UserPermissionFlags;
+}
+/**
+ * A collection entry inside collection.db.
+ */
+interface CollectionEntry {
+  /**
+   * Name of the collection.
+   */
+  name: string | null;
+  /**
+   * Beatmap MD5 hashes contained in the collection.
+   */
+  beatmapMd5Hashes: Array<string | null>;
+}
+/**
+ * Top-level structure of collection.db.
+ */
+interface CollectionDatabase {
+  /**
+   * Database version.
+   */
+  version: number;
+  /**
+   * All collections stored in the database.
+   */
+  collections: CollectionEntry[];
+}
+/**
+ * Additional score payload written only for specific mods.
+ */
+interface ScoreAdditionalModInfo {
+  /**
+   * Total accuracy of all hits for Target Practice.
+   * Divide by the number of targets to obtain the in-game displayed accuracy.
+   */
+  targetPracticeAccuracy: number;
+}
+/**
+ * A score entry stored in scores.db.
+ */
+interface ScoreEntry {
+  /**
+   * osu! gameplay mode.
+   */
+  gameplayMode: GameplayMode;
+  /**
+   * Version of this score or replay.
+   */
+  version: number;
+  /**
+   * Beatmap MD5 hash.
+   */
+  beatmapMd5Hash: string | null;
+  /**
+   * Player name.
+   */
+  playerName: string | null;
+  /**
+   * Replay MD5 hash.
+   */
+  replayMd5Hash: string | null;
+  /**
+   * Number of 300s.
+   */
+  count300: number;
+  /**
+   * Number of 100s, 150s, or mode-specific equivalent judgements.
+   */
+  count100: number;
+  /**
+   * Number of 50s or mode-specific equivalent judgements.
+   */
+  count50: number;
+  /**
+   * Number of gekis or max 300s.
+   */
+  countGeki: number;
+  /**
+   * Number of katus or 200s.
+   */
+  countKatu: number;
+  /**
+   * Number of misses.
+   */
+  countMiss: number;
+  /**
+   * Replay score.
+   */
+  totalScore: number;
+  /**
+   * Max combo.
+   */
+  maxCombo: number;
+  /**
+   * Perfect combo flag.
+   */
+  perfectCombo: boolean;
+  /**
+   * Bitwise combination of mods used.
+   */
+  mods: ModFlags;
+  /**
+   * Reserved string field that should always be empty in scores.db.
+   */
+  reservedEmptyString: string | null;
+  /**
+   * Replay timestamp, in .NET DateTime ticks.
+   */
+  replayTimestamp: DateTimeTicks;
+  /**
+   * Reserved 32-bit integer field that should always be 0xffffffff (-1).
+   */
+  reservedInt32: number;
+  /**
+   * Online score ID.
+   */
+  onlineScoreId: bigint;
+  /**
+   * Additional mod information.
+   * Present only if Target Practice is enabled.
+   */
+  additionalModInfo?: ScoreAdditionalModInfo;
+}
+/**
+ * A beatmap section stored in scores.db.
+ */
+interface ScoresBeatmapEntry {
+  /**
+   * Beatmap MD5 hash.
+   */
+  beatmapMd5Hash: string | null;
+  /**
+   * Scores stored for this beatmap.
+   */
+  scores: ScoreEntry[];
+}
+/**
+ * Top-level structure of scores.db.
+ */
+interface ScoresDatabase {
+  /**
+   * Database version.
+   */
+  version: number;
+  /**
+   * Beatmap score groups.
+   */
+  beatmaps: ScoresBeatmapEntry[];
+}
+//#endregion
+export { UserPermissionFlags as C, UserPermission as S, ScoreAdditionalModInfo as _, GameplayMode as a, ScoresDatabase as b, Grades as c, Mod as d, ModFlags as f, RankedStatuses as g, RankedStatus as h, DateTimeTicks as i, IntFloatPair as l, OsuDatabase as m, CollectionDatabase as n, GameplayModes as o, Mods as p, CollectionEntry as r, Grade as s, BeatmapEntry as t, MINIMUM_SUPPORTED_VERSION as u, ScoreEntry as v, UserPermissions as w, TimingPoint as x, ScoresBeatmapEntry as y };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "osu-stable-db",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "TypeScript reader and writer for osu!stable database files.",
+  "author": "zzzzv",
+  "license": "MIT",
+  "sideEffects": false,
+  "homepage": "https://github.com/zzzzv/osu-stable-db#readme",
+  "bugs": {
+    "url": "https://github.com/zzzzv/osu-stable-db/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zzzzv/osu-stable-db.git"
+  },
+  "keywords": [
+    "osu",
+    "osu-stable"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./node": "./dist/node.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "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",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}