@riverdogma/schema v0.10.0

@riverdogma/schema

@riverdogma/schema is a TypeScript library that provides a schema to create and manage song projects. It's designed to help people in the music realm to have a go-to schema for creating and managing their projects. The schema consists of phases and keywords which can be added to the basic schema through modifiers using the format --PHASE-ITERATION and --PHASE-ITERATION--KEYWORD-ITERATION.

Installation

Since this is an NPM package, you can install it using either NPM or pnpm.

With pnpm:

pnpm add @riverdogma/schema

With npm:

npm install @riverdogma/schema

Usage

This library provides a parse function and two types: Song and Schema.

Here's an example of how to use the parse function:

import parse from "@riverdogma/schema";

const songSchema = "20230512_my-song_C#_120--demo-1--intro-1";
const song = parse(songSchema);

console.log(song);

The parse function takes a schema string as input and returns an object that contains the parsed song details.

API

parse(schema: string) Parses a schema string and returns a song object. If the schema is invalid, it returns a SchemaError.

SchemaError

An error class that gets thrown when there's an issue with the schema parsing.

Development

This project uses changesets for versioning and tsup for bundling.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT

Credits

This library was created by Adam Silber-Gniady (@webspaceadam) and Fabio Oehme (@derivativecode), developers with a passion for music.

@riverdogma/schema

This library provides a method for parsing a specific type of string schema into a Song object. It also contains types for working with the Song object and errors that may occur during parsing.

Docs

Types

Our aim was to provide a type-safe way of working with the schema. To that end, we've created a number of types that can be used to describe the schema and the Song object.

SchemaError

A custom error class which extends the Error class. It has a property level which is of type ErrorLevel.

ErrorLevel

When an error occurs during parsing it can happen on different levels. This type describes the different levels of errors that can occur.

• "basic"
• "phase"
• "keyword"
• "badInput"

Schema

A union type of ProjectSchema, PhaseSchema, and PhaseKeywordSchema. This type is used to describe the schema string. The philosophy behind the Schema is that we can see directly in which phase a song is. Additionally to that we added the keyword possibility so for example a new sound selection approach in a demo phase can be used. Basically the Schema can be also described as a song state.

ProjectSchema

At the core we have the project schema. The goal of this schema is to provide an easy way to find a project in a folder structure. The project schema is the only required part of the schema. It consists of the creation date, the title, the key, and the bpm. The creation date is the date when the project was created. The title is the name of the song. The key is the key of the song. The bpm is the tempo of the song.

PhaseSchema

The phase schema is an optional part of the schema. It consists of the phase and the phase iteration. The phase is the phase of the song. The phase iteration is the iteration of the phase.

PhaseKeywordSchema

Another optional part of the schema. it consists of a keyword that can be anything and the iteration.

Song

An object with properties that describe a song. Properties include creationDate, title, key, bpm. It can optionally have phase, phaseIteration, keyword, and keywordIteration properties.

Note that the creationDate property is a string, not a Date object. This is because the schema is designed to be used in a file system, and file names cannot contain Date objects. The caller of the parse function is responsible for converting the string to a Date object if needed.

Phase

A type that can take any of the values from the PHASES array: "demo", "sketch", "premix", "mix", "master".

Methods

parse(schema: Schema): SchemaError | Song

This method accepts a schema string and tries to parse it into a Song object. If the schema is valid, it returns a Song object. If the schema is invalid, it returns a SchemaError.

Usage

import parse from "@riverdogma/schema";

const songSchema = "20230512_MySong_C#_120--demo-1";
const song = parse(songSchema);

if (!(song instanceof SchemaError)) {
  console.log(song.creationDate); // "20230512"
  console.log(song.title); // "MySong"
  console.log(song.key); // "C#"
  console.log(song.bpm); // 120
  console.log(song.phase); // "demo"
  console.log(song.phaseIteration); // 1
}

Note: If the songSchema string is not in a valid format, parse will return an instance of SchemaError. Always perform an instance check before using the result.