New time-signature module (#149)

README.md

@@ -108,6 +108,7 @@ The API documentation lives inside README.md file of each module
 
 #### Time, rhythm
 
+- [@tonaljs/time-signature](/packages/time-signature): Parse time signatures
 - [@tonaljs/duration-value](/packages/duration-value): Note duration values
 
 #### Utilities

package.json

@@ -34,7 +34,7 @@
  ".(ts|tsx)": "ts-jest"
  },
  "testEnvironment": "node",
- "testRegex": "(/__tests__/.*|\\.(test|spec))\\.(ts|tsx|js)$",
+ "testRegex": "test.ts$",
  "moduleFileExtensions": [
  "ts",
  "tsx",

packages/time-signature/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 danigb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

packages/time-signature/README.md

@@ -0,0 +1,78 @@
+# @tonaljs/time-signature ![tonal](https://img.shields.io/badge/@tonaljs-time_signature-yellow.svg?style=flat-square) [![npm version](https://img.shields.io/npm/v/@tonaljs/time-signature.svg?style=flat-square)](https://www.npmjs.com/package/@tonaljs/time-signature)
+
+> Functions to parse time signatures
+
+## Usage
+
+ES6:
+
+```js
+import { TimeSignature } from "@tonaljs/tonal";
+```
+
+node:
+
+```js
+const { TimeSignature } = require("@tonaljs/tonal");
+```
+
+single module:
+
+```js
+import TimeSignature from "@tonaljs/time-signature";
+```
+
+## API
+
+#### `TimeSignature.names() => string[]`
+
+Return a list of most most frequently-used time signatures:
+
+```js
+TimeSignature.names();
+```
+
+#### `TimeSignature.get(name: string | [number, number]) // => object`
+
+Get a time signature:
+
+```js
+TimeSignature.get("3/4"); // =>
+// {
+// empty: false,
+// name: "3/4",
+// upper: 3,
+// lower: 4,
+// type: "simple",
+// additive: []
+// };
+```
+
+`type` can be `simple`, `compound` or `regular`
+
+Additive signatures are accepted:
+
+```js
+TimeSignature.get("3+2+3/8"); // =>
+// {
+// empty: false,
+// name: '3+2+3/8',
+// type: 'irregular',
+// upper: 8,
+// lower: 8,
+// additive: [ 3, 2, 3 ]
+// }
+```
+
+Arrays can be passed as arguments:
+
+```js
+TimeSignature.get([3, 4]);
+TimeSignature.get(["3", "4"]);
+TimeSignature.get(["3+2+3", "8"]);
+```
+
+## References
+
+- https://en.wikipedia.org/wiki/Time_signature
+- https://en.wikipedia.org/wiki/Metre_(music)

packages/time-signature/index.ts

@@ -0,0 +1,102 @@
+// TYPES: PARSING
+export type TimeSignatureLiteral = string | [number, number] | [string, string];
+type ParsedTimeSignature = [number | number[], number];
+
+// TYPES: PROPERTIES
+export type ValidTimeSignature = {
+ readonly empty: false;
+ readonly name: string;
+ readonly upper: number | number[];
+ readonly lower: number;
+ readonly type: "simple" | "compound" | "irregular";
+ readonly additive: number[];
+};
+
+export type InvalidTimeSignature = {
+ readonly empty: true;
+ readonly name: "";
+ readonly upper: undefined;
+ readonly lower: undefined;
+ readonly type: undefined;
+ readonly additive: [];
+};
+
+export type TimeSignature = ValidTimeSignature | InvalidTimeSignature;
+
+// CONSTANTS
+const NONE: InvalidTimeSignature = {
+ empty: true,
+ name: "",
+ upper: undefined,
+ lower: undefined,
+ type: undefined,
+ additive: []
+};
+
+const NAMES = ["4/4", "3/4", "2/4", "2/2", "12/8", "9/8", "6/8", "3/8"];
+
+// PUBLIC API
+
+export function names() {
+ return NAMES.slice();
+}
+
+const REGEX = /^(\d?\d(?:\+\d)*)\/(\d)$/;
+const CACHE = new Map<TimeSignatureLiteral, TimeSignature>();
+
+export function get(literal: TimeSignatureLiteral): TimeSignature {
+ const cached = CACHE.get(literal);
+ if (cached) {
+ return cached;
+ }
+
+ const ts = build(parse(literal));
+ CACHE.set(literal, ts);
+ return ts;
+}
+
+export function parse(literal: TimeSignatureLiteral): ParsedTimeSignature {
+ if (typeof literal === "string") {
+ const [_, up, low] = REGEX.exec(literal) || [];
+ return parse([up, low]);
+ }
+
+ const [up, down] = literal;
+ const denominator = +down;
+ if (typeof up === "number") {
+ return [up, denominator];
+ }
+
+ const list = up.split("+").map(n => +n);
+ return list.length === 1 ? [list[0], denominator] : [list, denominator];
+}
+
+export default { names, parse, get };
+
+// PRIVATE
+
+function build([up, down]: ParsedTimeSignature): TimeSignature {
+ const upper = Array.isArray(up) ? up.reduce((a, b) => a + b, 0) : up;
+ const lower = down;
+ if (upper === 0 || lower === 0) {
+ return NONE;
+ }
+
+ const name = Array.isArray(up) ? `${up.join("+")}/${down}` : `${up}/${down}`;
+ const additive = Array.isArray(up) ? up : [];
+ const type =
+ lower === 4 || lower === 2
+ ? "simple"
+ : lower === 8 && upper % 3 === 0
+ ? "compound"
+ : "irregular";
+
+ return {
+ empty: false,
+ name,
+ type,
+ upper,
+ lower,
+ additive
+ };
+}

packages/time-signature/package.json

@@ -0,0 +1,26 @@
+{
+ "name": "@tonaljs/time-signature",
+ "version": "3.6.0",
+ "description": "Musical time signatures",
+ "scripts": {
+ "build": "rollup -c=../../rollup.config.js"
+ },
+ "keywords": [
+ "time signature",
+ "time meter",
+ "metre",
+ "music",
+ "theory"
+ ],
+ "main": "dist/index.es5.js",
+ "module": "dist/index.esnext.js",
+ "files": [
+ "dist"
+ ],
+ "types": "dist/time-signature/index.d.ts",
+ "author": "[email protected]",
+ "license": "MIT",
+ "publishConfig": {
+ "access": "public"
+ }
+}

packages/time-signature/test.ts

@@ -0,0 +1,49 @@
+import TimeSignature from "./index";
+
+describe("time-signature", () => {
+ test("get", () => {
+ expect(TimeSignature.get("4/4")).toEqual({
+ empty: false,
+ name: "4/4",
+ type: "simple",
+ upper: 4,
+ lower: 4,
+ additive: []
+ });
+ });
+
+ test("get invalid", () => {
+ expect(TimeSignature.get("0/0").empty).toBe(true);
+ });
+
+ test("simple", () => {
+ expect(TimeSignature.get("4/4").type).toEqual("simple");
+ expect(TimeSignature.get("3/4").type).toEqual("simple");
+ expect(TimeSignature.get("2/4").type).toEqual("simple");
+ expect(TimeSignature.get("2/2").type).toEqual("simple");
+ });
+ test("compound", () => {
+ expect(TimeSignature.get("3/8").type).toEqual("compound");
+ expect(TimeSignature.get("6/8").type).toEqual("compound");
+ expect(TimeSignature.get("9/8").type).toEqual("compound");
+ expect(TimeSignature.get("12/8").type).toEqual("compound");
+ });
+
+ test("irregular", () => {
+ expect(TimeSignature.get("2+3+3/8").type).toEqual("irregular");
+ expect(TimeSignature.get("3+2+2/8").type).toEqual("irregular");
+ });
+
+ test("names", () => {
+ expect(TimeSignature.names()).toEqual([
+ "4/4",
+ "3/4",
+ "2/4",
+ "2/2",
+ "12/8",
+ "9/8",
+ "6/8",
+ "3/8"
+ ]);
+ });
+});

packages/tonal/index.ts

@@ -16,6 +16,7 @@ import Range from "@tonaljs/range";
 import RomanNumeral from "@tonaljs/roman-numeral";
 import Scale from "@tonaljs/scale";
 import ScaleType from "@tonaljs/scale-type";
+import TimeSignature from "@tonaljs/time-signature";
 
 export * from "@tonaljs/core";
 
@@ -44,7 +45,8 @@ export {
  RomanNumeral,
  Scale,
  ScaleType,
- // backwards
+ TimeSignature,
+ // backwards API compatibility (3.0)
  Tonal,
  PcSet,
  ChordDictionary,

packages/tonal/package.json

@@ -34,7 +34,8 @@
  "@tonaljs/range": "^3.5.0",
  "@tonaljs/roman-numeral": "^3.5.0",
  "@tonaljs/scale": "^3.5.1",
- "@tonaljs/scale-type": "^3.5.0"
+ "@tonaljs/scale-type": "^3.5.0",
+ "@tonaljs/time-signature": "^3.5.0"
  },
  "author": "[email protected]",
  "license": "MIT",

packages/tonal/tonal.test.ts

@@ -25,6 +25,7 @@ describe("@tonaljs/tonal", () => {
  "Scale",
  "ScaleDictionary",
  "ScaleType",
+ "TimeSignature",
  "Tonal",
  "accToAlt",
  "altToAcc",

rollup.config.js

@@ -7,26 +7,29 @@ const INPUT_FILE = path.join(PACKAGE_ROOT_PATH, "index.ts");
 const OUTPUT_DIR = path.join(PACKAGE_ROOT_PATH, "dist");
 const PKG_JSON = require(path.join(PACKAGE_ROOT_PATH, "package.json"));
 
-const formats = [{ dist: "umd", ts: "es5" }, { dist: "es", ts: "esnext" }];
+const OUTPUTS = [
+ { format: "umd", target: "es5" },
+ { format: "es", target: "esnext" }
+];
 
 const name = getUmdName(PKG_JSON.name);
 
-export default formats.map(format => ({
+export default OUTPUTS.map(format => ({
  input: INPUT_FILE,
  external: [
  ...Object.keys(PKG_JSON.dependencies || {}),
  ...Object.keys(PKG_JSON.peerDependencies || {})
  ],
  output: {
  name,
- file: path.join(OUTPUT_DIR, `index.${format.ts}.js`),
- format: format.dist,
+ file: path.join(OUTPUT_DIR, `index.${format.target}.js`),
+ format: format.format,
  sourcemap: true
  },
  plugins: [
  typescript({
  tsconfig: `tsconfig.json`,
- tsconfigOverride: { compilerOptions: { target: format.ts } }
+ tsconfigOverride: { compilerOptions: { target: format.target } }
  })
  ]
 }));
@@ -38,6 +41,6 @@ function getUmdName(packageName) {
  packageName
  );
  }
- const sufix = packageName.slice("@tonaljs/".length);
- return _.startCase(sufix).replace(" ", "");
+ const suffix = packageName.slice("@tonaljs/".length);
+ return _.startCase(suffix).replace(" ", "");
 }

tsconfig.json

@@ -11,5 +11,5 @@
  "moduleResolution": "node"
  },
  "include": ["packages/**/*.ts", "../../packages/**/*"],
- "exclude": ["node_modules", "packages/**/*.test.ts", "**/dist/**/*"]
+ "exclude": ["node_modules", "packages/**/*test.ts", "**/dist/**/*"]
 }

tslint.json

@@ -5,6 +5,7 @@
  "no-implicit-dependencies": true,
 
  // Disable recommended rules
+ "interface-over-type-literal": false,
  "interface-name": false,
  "object-literal-sort-keys": false,
  "no-shadowed-variable": false