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

@xbyorange/mercury

v1.5.0

Published

Mercury. Reactive CRUD data layer

Downloads

675

Readme

Build status Coverage Status Quality Gate

NPM dependencies Last commit Last release

NPM downloads License

Reactive CRUD data abstraction layer

Mercury Logo

Overview

Mercury provides an asynchronous CRUD data abstraction layer that can be used to isolate your code from specific methods of different data origins.

Provides:

  • "Origin" class from which your own specific origin implementation should extend.
    • CRUD. Define different methods for read, create, update, delete actions.
    • Asynchronous. Three properties are available for each method: value, loading, error.
    • Queryable. Applies queries to your CRUD methods using the built-in query method.
    • Chainable. Queries can be chained, the resultant query will be the extension of all.
    • Customizable. Custom queries can be added to the instances.
    • Cache. Use built-in cache to avoid the same query being executed more than once if not necessary.
    • Clean cache on demand with the built-in clean method.
    • Events emitter.You can add listeners to changes and cache events.
    • Extensible. Implement your own origins connectors, or use one of the already existant:
  • "Selector" constructor for combining or transforming the result of one or many origins.
    • Declarative. Declare which Origins your Selector needs to consume. Mercury will do the rest for you.
    • Composable. Can fetch data from Origins or from another Selectors.
    • Homogeneus. Provides exactly the same interface than origins. Consumers don't need to know if they are consuming an Origin or a Selector.
    • Cache. Implements a cache that avoids the execution of the same Selector and query more than once.
    • Reactive. When one of the related sources cache is cleaned, the Selector cache is cleaned too.
    • Switchable. Consumed "source" can be changed programatically.
    • Parallellizable. Can fetch data from declared sources in series or in parallel.
    • Queryable. Queries can be applied as in Origins. You can pass the query data to sources, or use it in the parser function, after all related sources data have been fetched.
  • "sources" singleton containing methods for managing all created mercury sources at a time.
    • Tags Mercury instances can be tagged to create "management" groups. "Cleaning" cache of all mercury sources tagged with "api" tag calling to a single method is easy, for example.

Install

npm i @xbyorange/mercury --save

A simple example

import { Selector, sources } from "@xbyorange/mercury";
import { Api } from "@xbyorange/mercury-api";

const booksCollection = new Api("http://api.library.com/books");
const authorsCollection = new Api("http://api.library.com/authors");

const booksWithAuthors = new Selector(
  booksCollection,
  authorsCollection,
  (booksResults, authorsResults) =>
      booksResults.map(book => ({
      ...book,
      authorName: authorsResults.find(author => author.id === book.author)
    }))
);

// Each book now includes an "authorName" property.
const results = await booksWithAuthors.read();

// Clean cache of books, authors, and booksWithAuthors at a time.
sources.clean();

This example uses the Api origin, which is not distributed in this package, but can clearly illustrate the usage of an Origin, and the intention of the library.

Origins

Examples

All examples in next docs will use the Api origin for a better comprehension of the library intention. Please refer to the mercury-api documentation for further info about an API origin usage.

For especific implementation of Origins, please refer to each correspondant docs:

Creating a new Origin implementation.

Please read the full Origin api docs to learn how to create origins.

Selectors

Usage Examples

All examples in next docs will use the Api origin for a better comprehension of the library intention. Please refer to the mercury-api documentation for further info about an API origin usage.

Api

Read the full Selector API documentation.

Unit testing

Some utilities are provided to make easier the task of testing Selectors. Please red the testing selectors docs.

Sources

All created Mercury origins or selectors are registered in the "sources" object, which provides methods for managing them all together, or by groups based in tags.

A simple example

import { sources } from "@xbyorange/mercury";

sources.clean();

sources.getByTag("need-auth").config({
  headers: {
    "authentication": "foo"
  }
})

Api

Read the full sources API documentation.

Usage with frameworks

React

Please refer to the react-mercury documentation to see how simple is the data-binding between React Components and the Mercury Sources.

Connect a source to all components that need it. Mercury will fetch data only when needed, and will avoid making it more than once, no matter how many components need the data.

Components will became reactive to CRUD actions automatically (dispatch a create action over a collection, and Mercury will refresh it automatically on any rendered binded component)

Contributing

Contributors are welcome. Please read the contributing guidelines and code of conduct.