Orchestra

A dependency-free, Typescipt-first, pure-function String manipulation library

Usage

Installation

Thank you for checking out Orchestra! To add Orchestra to your project, simply run the following:

# yarn
yarn add @juliancoleman/orchestra

# npm
npm i @juliancoleman/orchestra

@juliancoleman?

I scope all my packages for the purpose of combining multiple packages into a single subdirectory, resulting in something like this...

lib/
node_modules/
  - @juliancoleman/
    - another-thing/
    - orchestra/
    - something/
src/

Instead of this...

lib/
node_modules/
  - another-thing/
  - orchestra/
  - something/
src/

This really helps clean up the node_modules directory. My packages aren't stuck intwined with acorn, ramda, react, uuid, and the likes of the thousands of other packages that were automatically downloaded when running yarn.

Contribute

Installation

Feel free to clone or fork this repo to start out. Once you're there, go ahead and run the following command(s):

# yarn
yarn

# npm
npm i

Q: I thought this was dependency-free???

A: This is to install dev-dependencies, which you will need if you decide you'd like to contribute.

There is no server framework for Orchestra, so you won't need to yarn start or any of that.

Testing

Note:

If you run into the following error while running the test suite on MacOS:

$ jest --config ./jest.config.js -i --watch
Error: `fsevents` unavailable (this watcher can only be used on Darwin)

then run the following:

brew install watchman

Test suite

The backbone of Orchestra's test suite is Jest. I chose Jest over mocha / chai for the reason that I have had the beautiful opportunity to use this as the testing framework for quite a few projects during my time at VideoAmp, and have built a solid understanding of the framework. The set up is stupid simple and includes its own matchers library, allowing me to use only one dev-dependency instead of two, resulting in smaller overhead.

You can run all tests in Orchestra by simply running:

# yarn
yarn test

# npm
npm run test

This command will spin up Jest, run all tests, and watch for additional changes to files. The watcher will restart if it detects a change in any .js or .ts file.

On the first run of Jest, it may report 0 suites found. Just hit a and let it find the suite.

Coverage reporting

Local

To view a map of the coverage report, run the following:

# yarn
yarn coverage

# npm
npm run coverage

This command will spin up jest, run all tests, run a coverage report, and print the report to the console. This command does not watch for file changes.

If you want to view a map of the coverage report (outside of Terminal), run the following command:

# yarn
yarn coverage:serve

# npm
npm run coverage:serve

This command will spin up Jest, run all tests, run a coverage report, and spin up a server to view the coverage report in the browser. Instructions for the URL will be printed out when the server is ready. This command does not watch for file changes.

Continuous Integration

A special command is used for Continuous Integration that you won't need to worry about. Just know that it is there.

If you decide you'd like to run a service like Travis with the help of Replicated for on-premises continuous integration, follow this demo to get started. The demo includes configs for both Travis and Circle CI.

For Orchestra, I feel this practice would be general overkill. But this library is architected to help support that for developer practice.

Writing your own tests

Jest has a very familiar feel to the likes of mocha and chai. To be as basic as possible, your test file will look something like this...

describe("#myFunction", () => {
  it("passes the test", () => {
    expect(true).toBe(true);
  });
});

That wasn't so difficult, was it? Let's cover some more...

Creating a new Orchestra method

So, you have a great idea on a new function you would like Orchestra to adopt. I appreciate the contribution!

1. Hop into the lib/ directory and create a new folder

The folder structure should look like the following

myFunction/
  - myFunction.ts
  - myFunction.spec.ts

(don't worry about the index.ts files)

2. Begin creating your function.
   • Don't forget to utilize TypeScript and its type system.
   • Any contribution with missing types will be automatically rejected.
3. Test your function.
   • use the example above to get started.
   • write as many tests you feel are necessary (the more, the better!).
   • Leaving the demo describe block in your test file will also earn you a rejection.
4. Upon completion of the function and its tests, run the following command:

# yarn
yarn generate-barrels

# npm
npm run generate-barrels

This will automatically add an index.ts file to your new folder, as well as add your new function to the list of Orchestra's module exports. You won't need to worry about populating the index as barrelsby has already taken care of that for you. If you're unfamiliar with the barrel pattern, I can't recommend reading up on it enough.

You can then do something like this in a project that uses Orchestra as a dependency:

import { myFunction } from "orchestra";

Pathing issues? What are those? Barrels seek to solve this problem, which is why I've adopted this pattern even in my smaller projects.