musicxml-io 0.8.0 → 0.8.2

package/README.md

@@ -360,7 +360,23 @@ Entry-level helpers for individual notes, directions, and parts.
 ```typescript
 import { transpose } from 'musicxml-io/operations';
 import { findNotes } from 'musicxml-io/query';
-import { isRest, getPartName } from 'musicxml-io/entry-accessors';
+import { isRest, getPartName } from 'musicxml-io/accessors';
+```
+
+The package declares `"sideEffects": false`, so bundlers can drop everything
+you don't import — pulling in only `parse` costs roughly 50 KB minified
+(~14 KB gzip).
+
+### Browser usage
+
+The main entry exports the Node-only file helpers (`parseFile`,
+`serializeToFile`), which depend on `fs`. Bundlers that honor the `browser`
+condition (webpack, Vite, esbuild with `--platform=browser`, etc.)
+automatically get a browser-safe build without any `fs`/`node:*` imports.
+You can also import it explicitly:
+
+```typescript
+import { parse, serialize } from 'musicxml-io/browser';
 ```
 
 ## Unique Element IDs
@@ -369,9 +385,9 @@ All elements in the Score structure have a unique `_id` property that is automat
 - MusicXML is parsed/imported
 - New elements are created via operations
 
-The ID format is `"i" + nanoid(10)` (11 characters total), where:
+The ID format is `"i"` + 10 random characters (11 characters total), where:
 - `"i"` prefix ensures XML ID compatibility (IDs must start with a letter or underscore)
-- `nanoid(10)` generates a URL-safe unique identifier
+- the suffix is drawn from a 64-character URL-safe alphabet backed by `crypto.getRandomValues` (same format as nanoid)
 
 ```typescript
 import { parse, generateId } from 'musicxml-io';

package/dist/accessors/index.d.mts

@@ -0,0 +1,185 @@
+import { l as DirectionType, D as DirectionEntry, N as NoteEntry, c as PartListEntry, P as PartInfo, S as Score } from '../types-B_6pqTfs.mjs';
+
+/**
+ * Entry-level accessors for DirectionEntry, NoteEntry, and PartInfo
+ *
+ * These are simple helper functions for working with individual entries,
+ * complementing the score-level query functions in ./query.
+ */
+
+/**
+ * Extracts a specific DirectionType union member by its kind
+ */
+type DirectionTypeOfKind<K extends DirectionType['kind']> = Extract<DirectionType, {
+    kind: K;
+}>;
+/**
+ * Get the first direction type of a specific kind from a DirectionEntry
+ *
+ * @example
+ * const dynamics = getDirectionOfKind(entry, 'dynamics');
+ * if (dynamics) {
+ *   console.log(dynamics.value); // 'ff', 'pp', etc.
+ * }
+ */
+declare function getDirectionOfKind<K extends DirectionType['kind']>(entry: DirectionEntry, kind: K): DirectionTypeOfKind<K> | undefined;
+/**
+ * Get all direction types of a specific kind from a DirectionEntry
+ *
+ * @example
+ * const allWords = getDirectionsOfKind(entry, 'words');
+ * allWords.forEach(w => console.log(w.text));
+ */
+declare function getDirectionsOfKind<K extends DirectionType['kind']>(entry: DirectionEntry, kind: K): DirectionTypeOfKind<K>[];
+/**
+ * Check if a DirectionEntry contains a specific direction type
+ *
+ * @example
+ * if (hasDirectionOfKind(entry, 'metronome')) {
+ *   // Handle tempo marking
+ * }
+ */
+declare function hasDirectionOfKind(entry: DirectionEntry, kind: DirectionType['kind']): boolean;
+/**
+ * Get tempo from DirectionEntry.sound
+ *
+ * @example
+ * const tempo = getSoundTempo(entry); // 120
+ */
+declare function getSoundTempo(entry: DirectionEntry): number | undefined;
+/**
+ * Get dynamics value from DirectionEntry.sound (MIDI velocity 0-127)
+ *
+ * @example
+ * const dynamics = getSoundDynamics(entry); // 80
+ */
+declare function getSoundDynamics(entry: DirectionEntry): number | undefined;
+/**
+ * Get damper pedal state from DirectionEntry.sound
+ */
+declare function getSoundDamperPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Get soft pedal state from DirectionEntry.sound
+ */
+declare function getSoundSoftPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Get sostenuto pedal state from DirectionEntry.sound
+ */
+declare function getSoundSostenutoPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Check if a NoteEntry is a rest
+ *
+ * @example
+ * if (isRest(note)) {
+ *   console.log('This is a rest');
+ * }
+ */
+declare function isRest(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a pitched note (has pitch information)
+ *
+ * @example
+ * if (isPitchedNote(note)) {
+ *   console.log(`Note: ${note.pitch!.step}${note.pitch!.octave}`);
+ * }
+ */
+declare function isPitchedNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is an unpitched note (percussion)
+ */
+declare function isUnpitchedNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is part of a chord (shares onset with previous note)
+ *
+ * @example
+ * const chordNotes = notes.filter(isChordNote);
+ */
+declare function isChordNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a grace note
+ *
+ * @example
+ * if (isGraceNote(note)) {
+ *   console.log('Grace note with slash:', note.grace?.slash);
+ * }
+ */
+declare function isGraceNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any tie (start, stop, or continue)
+ *
+ * @example
+ * if (hasTie(note)) {
+ *   // Note is tied to another note
+ * }
+ */
+declare function hasTie(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has a tie start
+ */
+declare function hasTieStart(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has a tie stop
+ */
+declare function hasTieStop(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a cue note
+ */
+declare function isCueNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any beams
+ */
+declare function hasBeam(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any lyrics
+ */
+declare function hasLyrics(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any notations (articulations, slurs, ornaments, etc.)
+ */
+declare function hasNotations(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is part of a tuplet
+ */
+declare function hasTuplet(entry: NoteEntry): boolean;
+/**
+ * Check if a PartListEntry is a PartInfo (score-part)
+ */
+declare function isPartInfo(entry: PartListEntry): entry is PartInfo;
+/**
+ * Get PartInfo by part ID
+ *
+ * @example
+ * const partInfo = getPartInfo(score, 'P1');
+ * if (partInfo) {
+ *   console.log(partInfo.name); // 'Piano'
+ * }
+ */
+declare function getPartInfo(score: Score, partId: string): PartInfo | undefined;
+/**
+ * Get part name by part ID
+ *
+ * @example
+ * const name = getPartName(score, 'P1'); // 'Piano'
+ */
+declare function getPartName(score: Score, partId: string): string | undefined;
+/**
+ * Get part abbreviation by part ID
+ *
+ * @example
+ * const abbr = getPartAbbreviation(score, 'P1'); // 'Pno.'
+ */
+declare function getPartAbbreviation(score: Score, partId: string): string | undefined;
+/**
+ * Get all PartInfo entries from a score
+ */
+declare function getAllPartInfos(score: Score): PartInfo[];
+/**
+ * Get a map of part ID to part name
+ *
+ * @example
+ * const names = getPartNameMap(score);
+ * // { 'P1': 'Piano', 'P2': 'Violin' }
+ */
+declare function getPartNameMap(score: Score): Record<string, string | undefined>;
+
+export { type DirectionTypeOfKind, getAllPartInfos, getDirectionOfKind, getDirectionsOfKind, getPartAbbreviation, getPartInfo, getPartName, getPartNameMap, getSoundDamperPedal, getSoundDynamics, getSoundSoftPedal, getSoundSostenutoPedal, getSoundTempo, hasBeam, hasDirectionOfKind, hasLyrics, hasNotations, hasTie, hasTieStart, hasTieStop, hasTuplet, isChordNote, isCueNote, isGraceNote, isPartInfo, isPitchedNote, isRest, isUnpitchedNote };

package/dist/accessors/index.d.ts

@@ -0,0 +1,185 @@
+import { l as DirectionType, D as DirectionEntry, N as NoteEntry, c as PartListEntry, P as PartInfo, S as Score } from '../types-B_6pqTfs.js';
+
+/**
+ * Entry-level accessors for DirectionEntry, NoteEntry, and PartInfo
+ *
+ * These are simple helper functions for working with individual entries,
+ * complementing the score-level query functions in ./query.
+ */
+
+/**
+ * Extracts a specific DirectionType union member by its kind
+ */
+type DirectionTypeOfKind<K extends DirectionType['kind']> = Extract<DirectionType, {
+    kind: K;
+}>;
+/**
+ * Get the first direction type of a specific kind from a DirectionEntry
+ *
+ * @example
+ * const dynamics = getDirectionOfKind(entry, 'dynamics');
+ * if (dynamics) {
+ *   console.log(dynamics.value); // 'ff', 'pp', etc.
+ * }
+ */
+declare function getDirectionOfKind<K extends DirectionType['kind']>(entry: DirectionEntry, kind: K): DirectionTypeOfKind<K> | undefined;
+/**
+ * Get all direction types of a specific kind from a DirectionEntry
+ *
+ * @example
+ * const allWords = getDirectionsOfKind(entry, 'words');
+ * allWords.forEach(w => console.log(w.text));
+ */
+declare function getDirectionsOfKind<K extends DirectionType['kind']>(entry: DirectionEntry, kind: K): DirectionTypeOfKind<K>[];
+/**
+ * Check if a DirectionEntry contains a specific direction type
+ *
+ * @example
+ * if (hasDirectionOfKind(entry, 'metronome')) {
+ *   // Handle tempo marking
+ * }
+ */
+declare function hasDirectionOfKind(entry: DirectionEntry, kind: DirectionType['kind']): boolean;
+/**
+ * Get tempo from DirectionEntry.sound
+ *
+ * @example
+ * const tempo = getSoundTempo(entry); // 120
+ */
+declare function getSoundTempo(entry: DirectionEntry): number | undefined;
+/**
+ * Get dynamics value from DirectionEntry.sound (MIDI velocity 0-127)
+ *
+ * @example
+ * const dynamics = getSoundDynamics(entry); // 80
+ */
+declare function getSoundDynamics(entry: DirectionEntry): number | undefined;
+/**
+ * Get damper pedal state from DirectionEntry.sound
+ */
+declare function getSoundDamperPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Get soft pedal state from DirectionEntry.sound
+ */
+declare function getSoundSoftPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Get sostenuto pedal state from DirectionEntry.sound
+ */
+declare function getSoundSostenutoPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Check if a NoteEntry is a rest
+ *
+ * @example
+ * if (isRest(note)) {
+ *   console.log('This is a rest');
+ * }
+ */
+declare function isRest(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a pitched note (has pitch information)
+ *
+ * @example
+ * if (isPitchedNote(note)) {
+ *   console.log(`Note: ${note.pitch!.step}${note.pitch!.octave}`);
+ * }
+ */
+declare function isPitchedNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is an unpitched note (percussion)
+ */
+declare function isUnpitchedNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is part of a chord (shares onset with previous note)
+ *
+ * @example
+ * const chordNotes = notes.filter(isChordNote);
+ */
+declare function isChordNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a grace note
+ *
+ * @example
+ * if (isGraceNote(note)) {
+ *   console.log('Grace note with slash:', note.grace?.slash);
+ * }
+ */
+declare function isGraceNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any tie (start, stop, or continue)
+ *
+ * @example
+ * if (hasTie(note)) {
+ *   // Note is tied to another note
+ * }
+ */
+declare function hasTie(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has a tie start
+ */
+declare function hasTieStart(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has a tie stop
+ */
+declare function hasTieStop(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a cue note
+ */
+declare function isCueNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any beams
+ */
+declare function hasBeam(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any lyrics
+ */
+declare function hasLyrics(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any notations (articulations, slurs, ornaments, etc.)
+ */
+declare function hasNotations(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is part of a tuplet
+ */
+declare function hasTuplet(entry: NoteEntry): boolean;
+/**
+ * Check if a PartListEntry is a PartInfo (score-part)
+ */
+declare function isPartInfo(entry: PartListEntry): entry is PartInfo;
+/**
+ * Get PartInfo by part ID
+ *
+ * @example
+ * const partInfo = getPartInfo(score, 'P1');
+ * if (partInfo) {
+ *   console.log(partInfo.name); // 'Piano'
+ * }
+ */
+declare function getPartInfo(score: Score, partId: string): PartInfo | undefined;
+/**
+ * Get part name by part ID
+ *
+ * @example
+ * const name = getPartName(score, 'P1'); // 'Piano'
+ */
+declare function getPartName(score: Score, partId: string): string | undefined;
+/**
+ * Get part abbreviation by part ID
+ *
+ * @example
+ * const abbr = getPartAbbreviation(score, 'P1'); // 'Pno.'
+ */
+declare function getPartAbbreviation(score: Score, partId: string): string | undefined;
+/**
+ * Get all PartInfo entries from a score
+ */
+declare function getAllPartInfos(score: Score): PartInfo[];
+/**
+ * Get a map of part ID to part name
+ *
+ * @example
+ * const names = getPartNameMap(score);
+ * // { 'P1': 'Piano', 'P2': 'Violin' }
+ */
+declare function getPartNameMap(score: Score): Record<string, string | undefined>;
+
+export { type DirectionTypeOfKind, getAllPartInfos, getDirectionOfKind, getDirectionsOfKind, getPartAbbreviation, getPartInfo, getPartName, getPartNameMap, getSoundDamperPedal, getSoundDynamics, getSoundSoftPedal, getSoundSostenutoPedal, getSoundTempo, hasBeam, hasDirectionOfKind, hasLyrics, hasNotations, hasTie, hasTieStart, hasTieStop, hasTuplet, isChordNote, isCueNote, isGraceNote, isPartInfo, isPitchedNote, isRest, isUnpitchedNote };

package/dist/accessors/index.js

@@ -0,0 +1,58 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+var _chunkOEX7NVZNjs = require('../chunk-OEX7NVZN.js');
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.getAllPartInfos = _chunkOEX7NVZNjs.getAllPartInfos; exports.getDirectionOfKind = _chunkOEX7NVZNjs.getDirectionOfKind; exports.getDirectionsOfKind = _chunkOEX7NVZNjs.getDirectionsOfKind; exports.getPartAbbreviation = _chunkOEX7NVZNjs.getPartAbbreviation; exports.getPartInfo = _chunkOEX7NVZNjs.getPartInfo; exports.getPartName = _chunkOEX7NVZNjs.getPartName; exports.getPartNameMap = _chunkOEX7NVZNjs.getPartNameMap; exports.getSoundDamperPedal = _chunkOEX7NVZNjs.getSoundDamperPedal; exports.getSoundDynamics = _chunkOEX7NVZNjs.getSoundDynamics; exports.getSoundSoftPedal = _chunkOEX7NVZNjs.getSoundSoftPedal; exports.getSoundSostenutoPedal = _chunkOEX7NVZNjs.getSoundSostenutoPedal; exports.getSoundTempo = _chunkOEX7NVZNjs.getSoundTempo; exports.hasBeam = _chunkOEX7NVZNjs.hasBeam; exports.hasDirectionOfKind = _chunkOEX7NVZNjs.hasDirectionOfKind; exports.hasLyrics = _chunkOEX7NVZNjs.hasLyrics; exports.hasNotations = _chunkOEX7NVZNjs.hasNotations; exports.hasTie = _chunkOEX7NVZNjs.hasTie; exports.hasTieStart = _chunkOEX7NVZNjs.hasTieStart; exports.hasTieStop = _chunkOEX7NVZNjs.hasTieStop; exports.hasTuplet = _chunkOEX7NVZNjs.hasTuplet; exports.isChordNote = _chunkOEX7NVZNjs.isChordNote; exports.isCueNote = _chunkOEX7NVZNjs.isCueNote; exports.isGraceNote = _chunkOEX7NVZNjs.isGraceNote; exports.isPartInfo = _chunkOEX7NVZNjs.isPartInfo; exports.isPitchedNote = _chunkOEX7NVZNjs.isPitchedNote; exports.isRest = _chunkOEX7NVZNjs.isRest; exports.isUnpitchedNote = _chunkOEX7NVZNjs.isUnpitchedNote;

package/dist/accessors/index.mjs

@@ -0,0 +1,58 @@
+import {
+  getAllPartInfos,
+  getDirectionOfKind,
+  getDirectionsOfKind,
+  getPartAbbreviation,
+  getPartInfo,
+  getPartName,
+  getPartNameMap,
+  getSoundDamperPedal,
+  getSoundDynamics,
+  getSoundSoftPedal,
+  getSoundSostenutoPedal,
+  getSoundTempo,
+  hasBeam,
+  hasDirectionOfKind,
+  hasLyrics,
+  hasNotations,
+  hasTie,
+  hasTieStart,
+  hasTieStop,
+  hasTuplet,
+  isChordNote,
+  isCueNote,
+  isGraceNote,
+  isPartInfo,
+  isPitchedNote,
+  isRest,
+  isUnpitchedNote
+} from "../chunk-R6JMBTUB.mjs";
+export {
+  getAllPartInfos,
+  getDirectionOfKind,
+  getDirectionsOfKind,
+  getPartAbbreviation,
+  getPartInfo,
+  getPartName,
+  getPartNameMap,
+  getSoundDamperPedal,
+  getSoundDynamics,
+  getSoundSoftPedal,
+  getSoundSostenutoPedal,
+  getSoundTempo,
+  hasBeam,
+  hasDirectionOfKind,
+  hasLyrics,
+  hasNotations,
+  hasTie,
+  hasTieStart,
+  hasTieStop,
+  hasTuplet,
+  isChordNote,
+  isCueNote,
+  isGraceNote,
+  isPartInfo,
+  isPitchedNote,
+  isRest,
+  isUnpitchedNote
+};