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

@jointly/cache-candidate-plugin-base

v2.0.0

Published

This is a library providing types needed to create a plugin for cache-candidate.

Downloads

3,125

Readme

What is this?

This is a basic repository for @jointly/cache-candidate that provides types needed to create a cache-candidate plugin.
This library is not meant to be used directly, but rather as a dependency for better types when creating your own plugin.
This library is used by all First Party Plugins of the cache-candidate ecosystem.
You can develop a library without using this library as this only provides some types, but we strongly recommend using it.

How To Create a Plugin

To create a plugin, you have to declare a variable of type CacheCandidatePlugin.
This variable must be exported, so that the plugin can be loaded by cache-candidate.

import { CacheCandidatePlugin, Hooks } from '@jointly/cache-candidate-plugin-base';

export const myPlugin: CacheCandidatePlugin = {
  name: 'myPlugin',
  hooks: [
    {
      hook: Hooks.SETUP,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.SETUP', payload, additionalParameters);
      }
    },
    {
      hook: Hooks.INIT,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.INIT', payload, additionalParameters);
      }
    },
    {
      hook: Hooks.EXECUTION_PRE,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.EXECUTION_PRE', payload, additionalParameters);
      }
    },
    {
      hook: Hooks.EXECUTION_POST,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.EXECUTION_POST', payload, additionalParameters);
      }
    },
    {
      hook: Hooks.DATACACHE_RECORD_ADD_PRE,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.DATACACHE_RECORD_ADD_PRE', payload, additionalParameters);
      }
    },
    {
      hook: Hooks.DATACACHE_RECORD_ADD_POST,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.DATACACHE_RECORD_ADD_POST', payload, additionalParameters);
      }
    },
    {
      hook: Hooks.DATACACHE_RECORD_DELETE_PRE,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.DATACACHE_RECORD_DELETE_PRE', payload, additionalParameters);
      }
    },
    {
      hook: Hooks.DATACACHE_RECORD_DELETE_POST,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.DATACACHE_RECORD_DELETE_POST', payload, additionalParameters);
      }
    },
    {
      hook: Hooks.CACHE_HIT,
      action: async (payload, additionalParameters) => {
        // Do something
        console.log('Hooks.CACHE_HIT', payload, additionalParameters);
      }
    }
  ]
};

In the example above, we created a plugin named myPlugin that logs the payload of each hook.
The additionalParameters argument is an object that can be passed to the cache-candidate when calling its hooks.

import { cacheCandidate } from '@jointly/cache-candidate';
import { myPlugin } from 'my-plugin';

const myCachedFunction = cacheCandidate(myFunction, {
  // ... options
  plugins: [
    {
      ...myPlugin,
      additionalParameters: {
        foo: 'bar'
      }
    }
  ]
});

If you don't need additionalParameters, you can simply pass the plugin to the cache-candidate.

import { cacheCandidate } from '@jointly/cache-candidate';
import { myPlugin } from 'my-plugin';

const myCachedFunction = cacheCandidate(myFunction, {
  // ... options
  plugins: [
    myPlugin
  ]
});

API

The CacheCandidatePlugin is an object composed of the following properties:

  • name: The name of the plugin. This name will be used to identify the plugin in the logs.
  • hooks: An array of ActionableHook that will be executed by cache-candidate.
    See Hooks for more information.

Glossary

Hooks

ActionableHook

An ActionableHook is a hook associated with an action that can be executed by cache-candidate.
It is composed of the following properties:

  • hook: The hook to execute.
    See Available Hooks for more information about the available hooks.
  • action: The action to execute when the hook is triggered.
    See Actions for more information about the available actions.

Available Hooks

All hooks are called only when the cache-candidate is executed in runtime.
The following hooks are available:

  • SETUP: Triggered when the cache-candidate firstly wraps the function/method.
    This gets called before any other operation is done.
    Please, consider the library will not wait for the execution of this hook.
    This is done to avoid blocking the execution of the initial execution.
  • INIT: Triggered when the candidate process is initialized.
    This gets called before any other operation is done, but only when the function is called.
  • EXECUTION_PRE: Triggered before the execution of the function/method wrapped in the cache-candidate.
  • EXECUTION_POST: Triggered after the execution of the function/method wrapped in the cache-candidate.
  • DATACACHE_RECORD_ADD_PRE: Triggered before the addition of a record in the cache.
  • DATACACHE_RECORD_ADD_POST: Triggered after the addition of a record in the cache.
  • DATACACHE_RECORD_DELETE_PRE: Triggered before the deletion of a record in the cache.
  • DATACACHE_RECORD_DELETE_POST: Triggered after the deletion of a record in the cache.
  • CACHE_HIT: Triggered when a cache hit occurs, before the result is returned. This also applies when a Running Query is returned (Please, refer to this paragraph and this paragraph for additional information).

Actions

Actions are functions that are executed by the cache-candidate when a hook is triggered.
Please, refer to the cache-candidate docs for more information about the arguments and their properties.
They take two arguments:

  • payload: The payload of the hook. It is composed of the following properties:
    • options: The options of the cache-candidate.
    • key: The key of the function/method wrapped in the cache-candidate. In case of SETUP, the key is an empty string "".
    • timeoutCache: The map containing the timeout bombs of the cache-candidate.
    • runningQueryCache: The running query cache of the cache-candidate.
    • timeframeCache: The timeframe cache of the cache-candidate.
    • fnArgs: The arguments of the function/method wrapped in the cache-candidate. In case of SETUP, the arguments are an empty array [].
    • internals: Internal functions and objects of the cache-candidate.
      These functions and objects are not meant to be directly modified by the plugins.
      They are exposed to the plugins for execution purposes.
      Internal functions are instantiated only once, therefore modifying them will affect all the cache-candidate instances.
      Please, refer to the exposed types and the @jointly/cache-candidate source code for additional information about the internals.
      The following internal functions are available:
      • getDataCacheRecord: A function that gets a record from the data cache.
      • addDataCacheRecord: A function that adds a record to the data cache.
      • deleteDataCacheRecord: A function that deletes a record from the data cache.
      • isDataCacheRecordExpired: A function that checks if a record is expired.
      • getDataCacheKey: A function that gets the key of a record in the data cache.
      • getExceedingAmount: A function that gets the exceeding amount of a record in the data cache.
        • As of cache-candidate v1.5.1, this function will expose a Promise instead of a number.
    • result (only for EXECUTION_POST and CACHE_HIT): The result of the function/method wrapped in the cache-candidate.
  • additionalParameters: The additional parameters passed to the plugin when calling its hooks.
    These parameters can be of any type and are used to pass additional information to the plugin.