JSOS1.0

Getting Started With JSOS Should You Use JSOS? Installation Installing Using NPM Installing A Browser Bundle Writing Your First Multimethod Debugging Types And Multimethods Where To Go From Here

Getting Started With JSOS

This short guide will help get you up and running with your first JSOS-based project.

Should You Use JSOS?

You should definitely use JSOS if...

  • ...you want your software to be easily extensible
  • ...you need multiple dispatch
  • ...you want some type safety, but don't like TypeScript or can't use it for your project

You might want to reconsider using JSOS if...

  • ...your JavaScript code is very performance-critical: JSOS is optimized for what it does, but of course it will always be a little slower than using plain old JavaScript functions
  • ...you already use TypeScript in your project and don't need multiple dispatch: having two different type systems in one project might be a little overkill
  • ...you cannot use ECMAScript modules in your project

Ready to start your JSOS-based project? Great, then read on!

Installation

First, of course, we need to install JSOS.

There's two ways to use JSOS in your project: You can either install it as a package from NPM or you can download a pre-built bundle and add it to your HTML file(s) using a script tag.

If you can, we recommend going with NPM instead of using a bundle.

Installing Using NPM

You can install JSOS using NPM like this:

npm i @fed1/jsos

This will install JSOS, and only JSOS. The library doesn't have any production dependencies, only some dev dependencies like ESLint and Mocha.

JSOS works out of the box in both the browser and node.js. For use in the browser, we recommend that you add an import map to your HTML.

Installing A Browser Bundle

At the time of this writing, JSOS has not seen a stable release and bundles are therefore not available for download.

You can, however, check out the source code and build the bundles yourself:

git clone https://git.fed1.org/jsos.git
npm i
npm run init
npm run bundle

Then you can use one of the bundles in the bundles/ folder. There are two versions available. The core bundle contains only what's listed under Core. The full bundle also contains everything under Standard Library.

Writing Your First Multimethod

Now that JSOS has been installed, you can dive right in and create your first multimethod and add methods to it. For example:

import { Generic, def, JSString } from "@fed1/jsos";

export const { multi } = Generic;

def(multi, [JSString], txt => console.log(txt));

Important:

If you want your software to be extensible, please remember to always export your multimethods and types!

Debugging Types And Multimethods

In general, you will find that JSOS always throws very helpful errors when something goes wrong.

Most of the time, these error messages contain, thanks to some funky JavaScript magic, not only the location of the throw, but also the location of any involved multimethods or methods (if it's a JSOS-related issue).

If you're working on the console and are unsure what JSOS type a value is, you can use the typeOf() function:

typeOf(something).name

If you're using JSOS in node.js or use the full bundle, you also have access to the introspection module. It contains a multimethod called explain that can give you really helpful information about multimethods and the types you use:

console.log(explain(theThingYouWantToBeExplained))

For example, when you call explain with a multimethod, you get an explanation of the multimethod, including a list of all its registered methods and where to find them!

See explain() for details.

Where To Go From Here

We highly recommend that you at least read the multimethod basic usage section in the documentation as well as the type system documentation.

You can also familiarize yourself with the API documentation and check out our examples for helpful recipes.

If you need help, you can check out our forum or join the FED1 Discord server.

Happy multimethod-driven development!