Add createEmptyChart() counterpart to parseChartAndIni

src/__tests__/create-chart.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Tests for createEmptyChart: the programmatic-build counterpart to parseChartAndIni.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { createEmptyChart } from '../chart/create-chart'
+import { defaultIniChartModifiers } from '../chart/note-parsing-interfaces'
+
+describe('createEmptyChart', () => {
+	it('uses defaults when no options are provided', () => {
+		const chart = createEmptyChart()
+
+		expect(chart.resolution).toBe(480)
+		expect(chart.tempos).toEqual([{ tick: 0, beatsPerMinute: 120, msTime: 0 }])
+		expect(chart.timeSignatures).toEqual([
+			{ tick: 0, numerator: 4, denominator: 4, msTime: 0, msLength: 0 },
+		])
+		expect(chart.format).toBe('chart')
+	})
+
+	it('honors resolution, bpm, and time signature overrides', () => {
+		const chart = createEmptyChart({
+			resolution: 192,
+			bpm: 150,
+			timeSignature: { numerator: 6, denominator: 8 },
+		})
+
+		expect(chart.resolution).toBe(192)
+		expect(chart.tempos[0].beatsPerMinute).toBe(150)
+		expect(chart.timeSignatures[0]).toMatchObject({ numerator: 6, denominator: 8 })
+	})
+
+	it('honors format override', () => {
+		const chart = createEmptyChart({ format: 'mid' })
+		expect(chart.format).toBe('mid')
+	})
+
+	it('produces a chart with empty metadata, tracks, and sections', () => {
+		const chart = createEmptyChart()
+
+		expect(chart.metadata).toEqual({})
+		expect(chart.drumType).toBeNull()
+		expect(chart.trackData).toEqual([])
+		expect(chart.sections).toEqual([])
+		expect(chart.endEvents).toEqual([])
+		expect(chart.unrecognizedEventsTrackTextEvents).toEqual([])
+		expect(chart.unrecognizedEventsTrackMidiEvents).toEqual([])
+		expect(chart.unrecognizedMidiTracks).toEqual([])
+		expect(chart.unrecognizedChartSections).toEqual([])
+		expect(chart.unrecognizedSyncTrackEvents).toEqual([])
+		expect(chart.parseIssues).toEqual([])
+	})
+
+	it('produces a chart with empty vocal tracks', () => {
+		const chart = createEmptyChart()
+		expect(chart.vocalTracks).toEqual({ parts: {}, rangeShifts: [], lyricShifts: [] })
+	})
+
+	it('produces a chart with empty chartBytes and default ini modifiers', () => {
+		const chart = createEmptyChart()
+		expect(chart.chartBytes).toBeInstanceOf(Uint8Array)
+		expect(chart.chartBytes.length).toBe(0)
+		expect(chart.iniChartModifiers).toBe(defaultIniChartModifiers)
+	})
+})

src/chart/create-chart.ts

@@ -0,0 +1,55 @@
+import { defaultIniChartModifiers } from './note-parsing-interfaces'
+import type { ParsedChart } from './parse-chart-and-ini'
+
+/**
+ * Build a minimal valid {@link ParsedChart} from scratch, without parsing any
+ * source bytes. Useful for programmatic chart generation and as the counterpart
+ * to `parseChartAndIni`.
+ *
+ * The returned chart has:
+ * - the requested resolution (default 480)
+ * - a single tempo event at tick 0 (default 120 BPM)
+ * - a single time signature at tick 0 (default 4/4)
+ * - empty metadata, tracks, sections, vocal parts, and unrecognized events
+ * - `chartBytes` set to an empty `Uint8Array` — there is no source file.
+ *   `scanChart()` will hash empty bytes (deterministic but not an identity);
+ *   callers that need a meaningful `chartHash` should serialize via
+ *   `writeChartFile`/`writeMidiFile` and re-parse.
+ * - `format` defaults to `'chart'` — the text format is the simpler target
+ *   for programmatic construction; pass `format: 'mid'` when the caller
+ *   needs `.mid` output.
+ * - `iniChartModifiers` set to the library defaults
+ */
+export function createEmptyChart(options?: {
+	format?: 'chart' | 'mid'
+	resolution?: number
+	bpm?: number
+	timeSignature?: { numerator: number; denominator: number }
+}): ParsedChart {
+	const resolution = options?.resolution ?? 480
+	const bpm = options?.bpm ?? 120
+	const numerator = options?.timeSignature?.numerator ?? 4
+	const denominator = options?.timeSignature?.denominator ?? 4
+	const format = options?.format ?? 'chart'
+
+	return {
+		resolution,
+		drumType: null,
+		metadata: {},
+		parseIssues: [],
+		vocalTracks: { parts: {}, rangeShifts: [], lyricShifts: [] },
+		endEvents: [],
+		unrecognizedEventsTrackTextEvents: [],
+		unrecognizedEventsTrackMidiEvents: [],
+		unrecognizedMidiTracks: [],
+		unrecognizedChartSections: [],
+		tempos: [{ tick: 0, beatsPerMinute: bpm, msTime: 0 }],
+		timeSignatures: [{ tick: 0, numerator, denominator, msTime: 0, msLength: 0 }],
+		unrecognizedSyncTrackEvents: [],
+		sections: [],
+		trackData: [],
+		chartBytes: new Uint8Array(0),
+		format,
+		iniChartModifiers: defaultIniChartModifiers,
+	}
+}

src/chart/index.ts

@@ -1,2 +1,3 @@
 export * from './chart-scanner'
+export * from './create-chart'
 export * from './parse-chart-and-ini'

src/index.ts

@@ -12,7 +12,7 @@ import { scanVideo } from './video'
 export * from './interfaces'
 export * from './chart/note-parsing-interfaces'
 export { parseChartFile } from './chart/notes-parser'
-export { parseChartAndIni } from './chart'
+export { parseChartAndIni, createEmptyChart } from './chart'
 export type { ParsedChart, ParseChartAndIniResult } from './chart'
 export { scanIni } from './ini'
 export { calculateTrackHash } from './chart/track-hasher'