Packages RFC

[sarahdayan]

This RFC outlines how to divide Dinero.js v2 into one or more npm packages for optimal developer and user experience.

It builds upon the existing package breakdown of the v2 alpha.

Motivation

The current v2 alpha is broken down between multiple packages:

dinero.js	The main package to use Dinero.js.
@dinero.js/currencies	Currency implementations for ISO 4217:2015 currencies.
@dinero.js/core	Internal functions, types, and common code shared across packages.
@dinero.js/calculator-number	Calculator implementation for the number type.
@dinero.js/calculator-bigint	Calculator implementation for the bigint type.

Not all these packages are relevant:

• Most users only need dinero.js and @dinero.js/currencies
• @dinero.js/core and @dinero.js/calculator-number are dinero.js dependency and have no use on their own

Having more packages than necessary hurts developer experience. For example, it's easy to have mismatched versions, and it makes users break their flow to install more packages.

Goals

• All packages should make sense. If a separate package exists, there should be a reason for it to be installed on its own—or a technical reason.
• There should be as few packages as possible. Each additional package adds to the cognitive load, so there should be exactly as many packages as necessary, not more.
• The chosen packaging method shouldn’t negatively impact build size. Specifically, UMD users shouldn’t suffer from it.

Proposal

This solution exposes a single package: dinero.js.

All existing @dinero.js/* packages are deprecated, and moved to the single package.

Rationale

When installing a package, you should be able to forget about it. Having to constantly think about what package contains what API, or whether you still need that package you added a few commits ago, creates friction that distracts users from what matters.

Separate packages should have unambiguously distinct concerns.

For example, a Vue and a React integration of a library should be in separate packages because they will never be used together in the same app.

Another example, an ESLint plugin for a library should be in a separate package. Although it’s designed to be used together when using the library, it’s a fully separate project and doesn’t share any code. Also, unlike the library, it’s a dev dependency. In back-end projects, it shouldn’t be installed at runtime.

Summary

The dinero.js package becomes the universal entry point to access everything in one place—core API and currencies.

The core API is accessible from the root of the package. Currencies are available from the /currencies path to avoid potential name clashes. It also keeps imports organized.

import { dinero, add } from 'dinero.js';
import { USD } from 'dinero.js/currencies';

const d1 = dinero({ amount: 500, currency: USD });
const d2 = dinero({ amount: 100, currency: USD });

add(d1, d2);

This lets users use the library without having to figure out how packages are broken down. Users who need the currencies have everything available from the first install—they don’t have to interrupt their flow, check the documentation, and install a separate package. If they realize they no longer need them, they don’t have to uninstall.

Users who don’t need currencies can just not use them. They can use the ESM bundle and tree-shake their app to get rid of unused code. If they use the UMD bundle, they can use separate endpoints.

Type implementations

Currently, the @dinero.js/calculator-bigint exposes a bigint calculator for users to use with the createDinero to make a bigint implementation themselves.

With this proposal, this separate package would go away. The previously exposed bigint calculator would be replaced by a ready to use bigint implementation. The package would also provide bigint currencies.

Type implementations are exposed via the /bigint path.

import { dinero, add } from 'dinero.js/bigint';
import { USD } from 'dinero.js/currencies/bigint';

const d1 = dinero({ amount: 500n, currency: USD });
const d2 = dinero({ amount: 100n, currency: USD });

add(d1, d2);

Note
Generic functions like add are aliased to be accessible from the /bigint path, but they’re the same as the number ones.

Only the dinero function and currencies are different.

UMD

When using the UMD bundle, users can pick separate endpoints to avoid bundling more code than they need.

<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/dinero.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/add.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/currencies/usd.production.js"></script>
<script>
  const { dinero } = window['dinero.js/dinero'];
  const { add } = window['dinero.js/add'];
  const { USD } = window['dinero.js/currencies/usd'];

  const d1 = dinero({ amount: 500, currency: USD });
  const d2 = dinero({ amount: 100, currency: USD });

  add(d1, d2);
</script>

They can load each endpoint in one request either by bundling them on their own with a build step, or using jsDelivr’s combine endpoint.

<script src="https://cdn.jsdelivr.net/combine/npm/dinero.js/dist/umd/dinero.production.js,npm/dinero.js/dist/umd/add.production.js,npm/dinero.js/dist/umd/currencies/usd.production.js"></script>

UMD users who aren’t concerned about bundle size can still access everything from the main endpoint.

<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/index.production.js"></script>
<script>
  const { dinero, add, USD } = window.dinero.js;

  const d1 = dinero({ amount: 500, currency: USD });
  const d2 = dinero({ amount: 100, currency: USD });

  add(d1, d2);
</script>

Usage

Working with number

ESM

import { dinero, add } from 'dinero.js';
import { USD } from 'dinero.js/currencies';

const d1 = dinero({ amount: 500, currency: USD });
const d2 = dinero({ amount: 100, currency: USD });

add(d1, d2);

With pinned currencies:

import { dinero, add } from 'dinero.js';
import { USD } from 'dinero.js/currencies/168';

const d1 = dinero({ amount: 500, currency: USD });
const d2 = dinero({ amount: 100, currency: USD });

add(d1, d2);

UMD

<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/dinero.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/add.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/currencies/usd.production.js"></script>
<script>
  const { dinero } = window['dinero.js/dinero'];
  const { add } = window['dinero.js/add'];
  const { USD } = window['dinero.js/currencies/usd'];

  const d1 = dinero({ amount: 500, currency: USD });
  const d2 = dinero({ amount: 100, currency: USD });

  add(d1, d2);
</script>

With pinned currencies:

<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/dinero.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/add.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/currencies/168/usd.production.js"></script>
<script>
  const { dinero } = window['dinero.js/dinero'];
  const { add } = window['dinero.js/add'];
  const { USD } = window['dinero.js/currencies/usd'];

  const d1 = dinero({ amount: 500, currency: USD });
  const d2 = dinero({ amount: 100, currency: USD });

  add(d1, d2);
</script>

Working with bigint

ESM

import { dinero, add } from 'dinero.js/bigint';
import { USD } from 'dinero.js/currencies/bigint';

const d1 = dinero({ amount: 500n, currency: USD });
const d2 = dinero({ amount: 100n, currency: USD });

add(d1, d2);

With pinned currencies:

import { dinero, add } from 'dinero.js/bigint';
import { USD } from 'dinero.js/currencies/bigint/168';

const d1 = dinero({ amount: 500, currency: USD });
const d2 = dinero({ amount: 100, currency: USD });

add(d1, d2);

UMD

<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/bigint/dinero.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/bigint/add.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/currencies/bigint/usd.production.js"></script>
<script>
  const { dinero } = window['dinero.js/dinero'];
  const { add } = window['dinero.js/add'];
  const { USD } = window['dinero.js/currencies/usd'];

  const d1 = dinero({ amount: 500, currency: USD });
  const d2 = dinero({ amount: 100, currency: USD });

  add(d1, d2);
</script>

With pinned currencies:

<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/bigint/dinero.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/bigint/add.production.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dinero.js/dist/umd/currencies/bigint/168/usd.production.js"></script>
<script>
  const { dinero } = window['dinero.js/dinero'];
  const { add } = window['dinero.js/add'];
  const { USD } = window['dinero.js/currencies/usd'];

  const d1 = dinero({ amount: 500, currency: USD });
  const d2 = dinero({ amount: 100, currency: USD });

  add(d1, d2);
</script>

[johnhooks]

I'm on board. This package layout would really simplify development and the build tooling. Would the core/src/api and dinero.js/src/api be merged?

[sarahdayan]

Yes, there would be a single dinero.js public package under packages/.

[johnhooks]

One thought that I'll add to the conversation is about possibly hiding the details of the genetic interface behind the common use cases. To the end user, they don't care that add or any of the other api functions are generic. Once they have chosen a number type, I expect they will use only the one. A tighter coupling between the calculator and api functions would simplify the usage for the end user. I suggest that each number type, supported by the library, export a set of api functions already initialized with the correct calculator. The documentation could be focused on the simplest use case and wouldn't even need to discuss TAmount or generics until explaining more advanced usage. IMHO I think it would be more accessible to general JavaScript developer and remove a possible hurdle to learning the library.

[sarahdayan]

Can you share more concretely what hiding those details would mean? Is this a documentation change? An API change?

Right now, you only care about it when creating your Dinero objects (you won't use the same dinero function because they each are tied to a different calculator) but then you use the same functions regardless of your amount type.

What would you simplify?

[johnhooks]

This is an example of what the dinero/src/number directory might look like (in the example its in a separate package because that's how the library is currently structured).

dinero-number-example

Here is a quick code example if you don't want to dive into the directory to get a look.

import { calculator } from '../calculator';

import { safeAdd } from '@dinero.js/core';
import type { AddParams, Dinero } from '@dinero.js/core';

const addFn = safeAdd(calculator);

/**
 * Add up the passed Dinero objects.
 *
 * @param augend - The Dinero object to add to.
 * @param addend - The Dinero object to add.
 *
 * @returns A new Dinero object.
 */
export function add(...[augend, addend]: AddParams<number>): Dinero<number> {
  return addFn(augend, addend);
}

It would create a little duplication between number and bigint, but two advantages I see are:

• cleaner function signatures
• most all the functions other than toDecimal and toUnits (because of the transformers) can be initialized outside the exported function, preventing recreating them every call.

It's just something I think would make it more approachable. Typescript is gaining a lot of adoption, but generics are still a bit intimidating to those that haven't taken the time to learn them.

EDIT: Now looking at it closer, it could be simplified even further:

import { calculator } from '../calculator';
import { safeAdd } from '@dinero.js/core';

/**
 * Add up the passed Dinero objects.
 *
 * @param augend - The Dinero object to add to.
 * @param addend - The Dinero object to add.
 *
 * @returns A new Dinero object.
 */
export const add = safeAdd(calculator);

There are definitely a lot of ways to do it, but I think the generic feature of the library is only important to the development of the library, not the end user, so simplifying it could be helpful.

[johnhooks]

Hopefully that makes sense. The distillation of the idea is, if a user of the library isn't directly using the generic interface of Dinero<TAmount>, then exposing it adds a layer of complexity that isn't required.

Edit: Though if this RFC is specifically about folder structure, sorry to complicate the discussion.

[johnhooks]

I've really been diving into dinero.js the last few days and experimenting with new ideas. I think I change my vote (though I can't do so because the UI doesn't let me).

This is the directory structure I suggest:

packages/
  # maintains same structure, though the api tests are moved to this package
  core/

  # `@dinero.js/big.js`, I figure this might as well be added, its already implemented and tested
  big.js/

  # `@dinero.js/bigint`
  bigint/

  # `dinero.js` is the the `number` type implementation
  dinero.js/

All of the implementation packages share this directory structure:

src/
  api/  # This could just be a re-export of the `@dinero.js/core` api functions, or tailored to the specific number type.
  calculator/
  currencies/

A user of the library only installs one package and that packages depends on dinero.js/core. It comes with everything necessary and is specific to the number type implementation.