Multiple Modes

[lukeed]

As with others of my modules, I think a "choose your path" option for this module would be great.

"default"

By default – aka, the regular import – a middle of the road approach should be offered that covers the majority of cases. As of today, this would be the current klona module, supporting Objects, Arrays, Dates, RegExps, Maps, Sets, all TypedArray variants (includes Buffer), and primitives, of course.

Using this mode will continue to look like this:

import klona from 'klona';

"full"

There will definitely be a "full" mode (name TBD) that does everything "default" does, but with these added features. I originally was going to publish klona with these features to start, but removed them since they don't fit the 90% use case IMO.

Of course, this mode will be a bit larger (~400 bytes) and significantly slower than the current klona – however it'll still be faster than most contenders of the current benchmark & none of them offer these extra features.

Again, this is opt-in behavior & I'm a fan of being explicit about what you need and where you need it. Using this mode will look like this:

import klona from 'klona/full'; // name TBD

"lite"

There will also be "lite" or "json" mode (name TBD) for handling simpler cases. I actually think the 90% use case doesn't bother with cloning RegExps, TypedArrays, or even Maps & Sets, but "default" included them to be safe.

The lite/json mode, as the name suggests, will handle far fewer cases than the "default" and "full" counterparts. Because of this, this mode will be ~200 bytes and the fastest of the three.

I'm still debating if this mode should handle RegExp and Date. If so, then the name would have to be "lite" – otherwise only valid JSON datatypes will remain, thus making "json" a clear & obvious choice for dealing with JSON data objects.

As with "full", using this mode is an opt-in behavior and should be obvious when you've made that choice. Using this mode will look like:

import klona from 'klona/lite';
// ~ OR ~
import klona from 'klona/json';

---

Please leave any comments or concerns or naming suggestions that you may have. This is planned for a minor/feature release since nothing changes to the default mode.

Thanks!

[erickwilder]

Perhaps these "modes" could be named exports instead of default exports. The rationale is that looking at a large code base you would have to either guess or skim through the list of imports to know exactly which version of klona was imported:

import klona from 'klona/lite'
// .. some large code base where the import statement is out of your mind later...
klona(here_we_expect_a_full_clone) // ouch!! not gonna work

Compared to:

import { fullKlona } from 'klona'
import { klonaLite } from 'klona'
import klona from 'klona' // always the "default" mode

This is very minor but consider that as one alternative for API design of the library. If the developer using the library chooses to alias it then it's a conscious decision which comes with all the pros/cons of aliasing in general.

[lukeed]

Thanks for the feedback 👍

In my mind, they're entirely separate entry points – or alternate versions – of themselves. I contrast that with named exports (or any exports) which are the actions that the module is capable of.

In this case, it's all the same action – just different flavors of it.

There's also the benefit of reduced parsed/network cost. With ESM-in-production growing, the need to respect bytes over the wire or time-to-parse doesn't suddenly disappear because you have a named export. You'd be juggling 700-850 bytes when you knew all you needed was 200.

Finally, I think naming is always a subjective thing. You can easily fall into the same predicament you've described by doing this:

import { full as klona } from 'klona';
// still requires that I knew "klona" === "full"

...or alias the multiple entries like this:

import klonaLite from 'klona/lite'

Either way, the dev is the one decidedly opting into a mode/version and has to keep its capabilities in mind. They can use whatever naming patterns they want to help serve as a reminder.

Does that sound reasonable?

[cbbfcd]

maybe as an optional param??:

import klona from 'klona';

klona(someObj, { mode: 'full' }); //default lite

[emilio-martinez]

My two cents: especially if the "lite" mode is truly the 90% case, separate entry points are probably preferred for tree-shaking purposes.

Approaches such as optional params, having multiple exports from a single entry point, and others make it much more likely to run into situations where users may be loading unused code depending on tooling situation. Having separate endpoints practically ensures the appropriate separation, even with bare ES import/exports.

[lukeed]

Exactly @emilio-martinez 👍