v5.3.0

More detailed change events

df853ef

IStorage instances now emit more detailed change events when a document is written (modified, created, deleted).

IStorage.onWrite is a newly added Emitter which sends out objects like this:

export type WriteEvent = {
    kind: 'DOCUMENT_WRITE',
    // a write is "local" if it comes from IStorage.set()
    // otherwise it's "remote" (it came from a sync).
    isLocal: boolean,
    document: Document,
}

Use it like this:

myStorage.onWrite((event: WriteEvent) => {
    console.log(`a document changed at ${document.path}`);
});

Deprecations

The previous Emitter, IStorage.onChange, still exists and is triggered in the same situations, but it does not send any info to callbacks. It's deprecated and will be removed eventually.

v5.2.6

Breaking change

• d178fe7 Emitter.changeKey is now a string, not a number.

v5.2.5

Changes

• f1a07ea Emitters have a new property: changeKey. It's a number that changes to a new random value as each event happens. It's useful for triggering re-renders in React, like this:

<MyComponent changeKey={storage.onChange.changeKey} />

v5.2.4

No public API changes.

Bugfixes

• Fix a possible bug with detRandom functions in browsers by inlining one of the buffer functions from node

Tooling

• Add Karma so we can run tests in the browser. This setup is a bit awkward; see karma.conf.js for instructions. Also change the test files so they work in both tap and tape, since tap is not browserifiable.

v5.2.3

Ephemeral documents are now usable

• d20fe44 -- Ephemeral docs are now required to have at least one ! character in their paths. Regular docs must not have a !. See #31 for background.

Ephemeral docs are now complete from an app's point of view. We still need to add a proactive hourly check to physically delete them for privacy purposes.

v5.2.1

Breaking change: deleteAfter field is no longer optional

commit b581143

The deleteAfter field in Document used to be optional. It's now required and is null when not being used:

// old
deleteAfter?: number

// new
deleteAfter: number | null

The documents you get from IStorage will now follow this new type.

Existing sqlite files are unaffected. Document hashes have also not changed, which means old documents still have valid signatures.

If you were using a StorageMemory and dumping its contents somewhere (like localStorage), the dump is in the old format and will need to be converted before loading it again.

New: deterministic random helper functions

commit e0eb930

import {
    detRandom,  -- random float between 0 and 1, derived from input string
    detChoice,  -- random choice from an array
    detRange, -- random float, you choose the range
    detInt,  -- random integer, you choose the range
} from 'earthstar'

Added functions to make it easier to randomly colorize authors depending on their author address. Please read the comments in the source for details about how to use it.

Breaking change: LowLevelCrypto.sha256

also in commit e0eb930

This is an internal function that's unlikely to have been used by apps.

LowLevelCrypto used to provide a function sha256base32 which returned the binary digest of sha256, encoded into a base32 string.

This function has been renamed and changed to:

LowLevelCrypt.sha256 -- returns a binary Buffer digest
crypto.sha256base32 -- encodes it into base32 for you

So now you can get the raw Buffer digest if you want it.

v5.1.0

Technically this is a breaking change but I'm being sloppy while the project is still small. :)

Changed

• In author profile info, the longname field has been renamed to displayName. (This is stored in profile.json documents and you can use the helper class LayerAbout to get and set it.) "Display name" is the new standard vocabulary for this -- it's not called a "long name" anymore.
• Path length is now limited to 512 characters. It was unlimited before. Previously created documents with longer paths are now invalid and will not sync. (This should have caused a version bump on es.4 but I'm being sloppy.)

Added

• New function: crypto.checkAuthorKeypairIsValid(keypair) -- check if the address and secret are a matching pair, and if the strings are in the expected format.
• Wrote most of specification.md which will replace older documentation.

Incomplete

• New query field contentIsEmpty?: boolean to limit the query to documents with or without empty content (e.g. "deleted documents"). Don't use this yet -- it only works on simple queries and we need to solve issue #44 first before finalizing it.

v5.0.0

Lots of breaking changes since v3.x!

(v4 was skipped, we're on v5 now.)

• Added lots of documentation files, linked to from the top of the README. Some of these are out of date.
• Added a code of conduct and contributing guide

Core document format

• Validator format bumped from es.3 to es.4
• Switched everything to base32 encoding. No more base58, no more hex. This affects hashes, pubkeys, secret keys, and signatures. This was done because upper case characters from base58 are not allowed in URL locations.
• Renamed document field value to content to make it feel more like a filesystem
• Question marks are no longer allowed in document paths because they conflict with URL parsing (query parameters)
• Change how documents are serialized for hashing to be safer if we add more optional fields later

Incomplete core changes

• To prepare for sparse mode, now the hash of document content is explicitly stored in contentHash, next to the content. Only the contentHash, not the content itself, is used when computing the document's hash. This allows dropping the actual content data but still verifying the document signature. You can't actually drop the content data yet though, see the linked issue for the remaining steps.
• Added ephemeral documents with an expiration date stored in the optional deleteAfter field. This works but will change a bit -- probably ephemeral documents will need to have a ! in their path, and we need to set up a timer to check for and delete them every hour in the Storage classes.

Javascript API

• Made error handling more consistent and explicit across the codebase. Docs about error handling. This is a breaking change. A bit more detail about the changes.
• ValidatorES3 --> ValidatorES4
• Rearranged internal ValidatorES4 methods that check if paths are valid, etc
• Parsing addresses (author, workspace) is now the responsibility of the Validator since these might have different rules in different validator versions
• Storage methods renamed: getValue --> getContent, and values --> contents
• Added Storage methods close() and isClosed(). Close a Storage when you know you won't be using it again. Internally it closes the SQLite file, turns off recurring setInterval functions, etc.

What's next?

Mostly things from the "acorn" milestone

• A more clearly written specification
• An async version of IStorage, so we can use IndexedDb?
• Finish sparse mode (dropping content but keeping the rest of the document)
• Finish ephemeral documents
• Think about making a core Document and Validator with basic rules, and having ValidatorES4 etc build on top of those. This could add some consistency across validator versions so that Storage classes can be sure to work on future versions.
• Implement sync filters

Ecosystem

Updated:

• earthstar-cli