# @riverdogma/schema

> A library for working with schemas for songs, to make your life as a musician easier.

Latest version **0.10.0** (published 2023-09-08) · ISC license · 0 weekly downloads

## Install

```sh
npm install @riverdogma/schema
pnpm add @riverdogma/schema
yarn add @riverdogma/schema
bun add @riverdogma/schema
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.10.0 |
| Published | 2023-09-08 |
| First published | 2023-05-03 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 18.3 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | derivativecode, webspaceadam |
| Keywords | schema, ableton, music, tagging, projectmanagement |

## Links

- npm: https://www.npmjs.com/package/@riverdogma/schema
- Repository: https://github.com/riverdogma/schema
- Homepage: https://github.com/riverdogma/schema#readme
- Issues: https://github.com/riverdogma/schema/issues
- npm.io page: https://npm.io/package/@riverdogma/schema

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^3.22.2

## Alternatives

- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads

## Recent versions

- 0.10.0 (latest) — 2023-09-08
- 0.9.0 — 2023-09-08
- 0.8.0 — 2023-09-08
- 0.7.1 — 2023-09-07
- 0.7.0 — 2023-09-07
- 0.6.1 — 2023-08-31
- 0.6.0 — 2023-08-24
- 0.5.0 — 2023-08-23
- 0.4.0 — 2023-05-25
- 0.3.0 — 2023-05-13
- 0.2.0 — 2023-05-12
- 0.1.0 — 2023-05-12
- 0.0.2 — 2023-05-04
- 0.0.1 — 2023-05-03

## README

# @riverdogma/schema

![Builds & Tests](https://github.com/riverdogma/schema/actions/workflows/main.yml/badge.svg)

`@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:

```shell
pnpm add @riverdogma/schema
```

With npm:

```shell
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:

```typescript
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).

#### 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

```typescript
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.

---
_Source: https://npm.io/package/@riverdogma/schema · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._