npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@kiruse/serde

v0.8.0-rc.6

Published

Binary serialization & deserialization API

Downloads

680

Readme

serde.ts

Please find the full documentation over at GitBook.

Quickstart

If your project has simple needs for serialization & deserialization, e.g. cross-session persistence, serde can get you started quickly. If your data type has no specific needs and consists only of standard types, serde works out of the box:

import Serde from '@kiruse/serde';
import { expect } from 'chai';
​
const serde = Serde().standard();
​
const ref = {
    foo: 'foo',
    bar: 42,
    baz: 69,
};
const bytes = serde.serialize(ref);
expect(serde.deserialize(bytes)).to.deep.equal(ref);
serde supports references, including cyclic references, and will reconstruct an object with identical hierarchy than your input:
import Serde from '@kiruse/serde';
​
const serde = Serde().standard();
​
// self-referential object
const ref: any = {};
ref.ref = ref;
​
const value = serde.deserialize(serde.serialize(ref));
value === value.ref;

setSimple Method

The Serde protocol is highly customizeable to various degrees. Indicative of its name, the Serde.prototype.setSimple method allows some more control than serializing plain old objects:

import Serde, { SERDE, StandardProtocolMap } from '@kiruse/serde';
import { expect } from 'chai';
​
type MyProtocolMap = StandardProtocolMap & {
    'my-foo': Foo;
}
​
class Foo {
    [SERDE] = 'my-foo' as const;
    constructor(public readonly id: number) {}
}
​
const serde = Serde<MyProtocolMap>().standard()
    .setSimple('my-foo',
        (foo: Foo) => foo.id,
        (id: Foo['id']) => new Foo(id),
    );

However, there is a caveat: due to the way serde internally handles references you only have direct access to first-level properties, i.e. you cannot access nested objects. serde promises that these special references are resolved and the object properly reconstructed after the call to deserialize. Within the deserialization process, certain rules must be considered. Read further at ​

set Method

Save for writing your own protocol, the highest degree of control is offered by the Serde.prototype.set method which grants you access to the Writer and Reader used during de/serialization as well as their contexts:

import Serde, { SERDE, StandardProtocolMap } from '@kiruse/serde';
​
type MyProtocolMap = StandardProtocolMap & {
    'my-foo': Foo;
}
​
class Foo {
    [SERDE] = 'my-foo' as const;
    constructor(public readonly id: number) {}
}
​
const serde = Serde().standard()
    .set('my-foo',
        (ctx, writer, foo: Foo) => {
            writer.writeUint32(foo.id);
        },
        (ctx, reader) => {
            return new Foo(reader.readUint32());
        },
    );

Caveats

It is impossible to de/serialize neither symbols nor functions:

While technically possible, deserializing functions (which includes constructors) would create duplicates as we cannot reference the original function without another global registry. Further, the prototype model would render this code highly complex. Further further, built-in/native functions cannot be de/serialized regardless. Finally, it poses an extreme security risk of code injection which should be avoided at all costs.

Symbols can technically be de/serialized, but as Symbols are unique at runtime, deserializing would again create incompatible duplicates. It would be possible to support through another registry, but this would once again require associating them with less unique strings, defeating the absolute uniqueness of symbols. In other words, two symbols can share the same display text. You can create your own Symbol('SERDE') symbol and it would still be unique from this library's SERDE symbol, thus not usable to specify the SerdeProtocol.