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

gdpr-guard

v2.4.1

Published

Simple GDPR manager

Downloads

39

Readme

gdpr-guard

Simple GDPR manager

This library helps you build a GPDR compliant system by providing you easy to manipulate interfaces.

Eco-system

There are a handful of libraries to help you along the way:

  • binding libraries, which ease the use with your favorite frameworks & libraries
  • persistence libraries, which offer you storage/persistence solutions

Bindings

  • html-gdpr-guard Use gdpr-guard as efficiently and easily as possible, based on data provided in the DOM
  • dom-gdpr-guard Use the JS DOM API to create elements based on the GdprManager's state and render it (can also use smart diffing)
  • vue-gdpr-guard A Vue 2 plugin that exposes global helpers as well as renderless components to help you build your UI easily (and optionally recursively)
  • vue3-gdpr-guard WIP A Vue 3 plugin that aims to be a Vue 3 alternative to vue-gdpr-guard, but based on the Composition API instead
  • react-gdpr-guard A React library that provides a hooks-creating function to interact with your GdprManager, in a react-way
  • ngx-gdpr-guard An Angular library that exposes a module and service to interact with your GdprManager, in an Angular and RXjs way
  • svelte-gdpr-guard Coming Soon
  • rx-gdpr-guard Coming Soon

Persistence

How to import

Using ES6-style imports:

import {
	//most useful
	GdprStorage,
	GdprManagerBuilder,
	GdprDeserializer,

	//helpers
	makeGuard,
	visitGdpr,
	GdprGuardGroup,
	GdprManager,
	GdprSerializer,
	GdprSaviorAdapter,
} from "gdpr-guard"

Using node style require:

const {
	//most useful
	GdprStorage,
	GdprManagerBuilder,
	GdprDeserializer,

	//helpers
	makeGuard,
	visitGdpr,
	GdprGuardGroup,
	GdprManager,
	GdprSerializer,
	GdprSaviorAdapter,
} = require("gdpr-guard");

Directly from your browser:

const {
	//most useful
	GdprStorage,
	GdprManagerBuilder,
	GdprDeserializer,

	//helpers
	makeGuard,
	visitGdpr,
	GdprGuardGroup,
	GdprManager,
	GdprSerializer,
	GdprSaviorAdapter,
} = gdprGuard;

What are the essential design choices to keep in mind

The name used for guards and groups must be unique! This is the identifier/key that binds it.

The wide concept of guard is that a guard is an entity that can be toggled to allow/deny some functionalities.

What is provided?

You can check the documentations here

GdprStorage

This is an enum-like type that lists the available storage options, these include:

  • None
  • Cookie
  • LocalStorage
  • SessionStorage
  • IndexedDb
  • FileSystem
  • ServerStorage
  • All

GdprManagerBuilder

GdprManagerBuilder provides a nice and easy to write/read way to create a GdprManager object from the groun up.

For instance you can use it like this:

const manager = GdprManagerBuilder
	.make()
		.startRequiredGroup(GdprStorage.Cookie, "Functionalities", "Information purely used for the user's experience")
		// This is a group that by default uses cookies for storage, every option and the group itself is required
			.withEnabledGuard("PHP_SESSID", "Server session identifier")
			.startGuard()
				.withName("theme")
				.withDescription("User's current colors' theme")
				.storedIn(GdprStorage.LocalStorage)
			.endGuard()
		.endGroup()
		.startGroup(GdprStorage.Cookie, "Advertisement", "Tracking-based avertisement informations")
			.startGroup(GdprStorage.Cookie, "Advertisement : Local", "Sitewide advertisement informations")
			// [...]
			.endGroup()
			.startGroup(GdprStorage.Cookie, "Advertisement : 3rd-party", "3rd-party advertisement informations")
			// [...]
			.endGroup()
		.endGroup()
	.build();

console.log(manager.raw()); // inspect useful information

GdprDeserializer

GdprDeserializer allows you to retrieve a gdpr object from its raw representation.

import { GdprManagerBuilder, GdprDeserializer } from "gdpr-guard"

// [...]

const manager = GdprManagerBuilder.make()
	// [...]
	.build();

const raw = manager.raw();
//store in local storage

const raw = //get from local storage
const manager = GdprDeserializer.manager(raw);
if (manager === null) { //failed deserialization
	//handle error
	return;
}

// here, both managers are equivalent

GdprManager

A GdprManager manages a list of GdprGuardGroup. You can :

  • get its most useful representation (raw())
  • add or create groups (respectively addGroup(guardGroup) and createGroup(name, description))
  • determine whether or not there is a specific guard (hasGuard(name))
  • retrieve a specific guard (getGuard(name))
  • determine whether or not there is a specific group (hasGroup(name))
  • get a specific group (getGroup(name))
  • determine if a guard/group is enabled (isEnabled(name))
  • enable everything except required (enable())
  • disable everything except required (disable())
  • toggle state, i.e. either enable all or disable all (toggle())
  • enable everything for a given storage (enableForStorage(gdprStorage))
  • disable everything for a given storage (disableForStorage(gdprStorage))
  • toggle state for a given storage (toggleForStorage(gdprStorage))

GdprGuardGroup

A GdprGuardGroup manages a list of GdprGuard (which includes raw guards, GdprGuardGroup and GdprManager although one would not recommend to put managers inside managers).

You can:

  • mark it as required, with every of its guards (makeRequired())
  • get its most useful representation (raw())
  • determine whether or not there is a specific guard (hasGuard(name))
  • retrieve a specific guard (getGuard(name))
  • determine if a guard/group is enabled (isEnabled(name))
  • enable everything except required (enable())
  • disable everything except required (disable())
  • toggle state, i.e. either enable all or disable all (toggle())
  • enable everything for a given storage (enableForStorage(gdprStorage))
  • disable everything for a given storage (disableForStorage(gdprStorage))
  • toggle state for a given storage (toggleForStorage(gdprStorage))

makeGuard

makeGuard is a function that creates the simplest guard possible, it has the following signature:

declare function makeGuard(name: string, description: string, storage?: GdprStorage, required?: boolean, enabled?: boolean | null): GdprGuard;

GdprSaviorAdapter

A class that implements most of the behavior for the Savior API.

abstract class GdprSaviorAdapter implements GdprSavior {
	public abstract restore(shouldUpdate?: boolean): Promise<GdprManager | null>;

	public abstract store(manager: GdprManagerRaw): Promise<boolean>;

	public abstract updateSharedManager(manager: GdprManager): Promise<void>;
}

Savior API

This API helps saving and restoring the manager state. It is exposed mainly for library authors as it helps creating various bindings for frameworks.

This is the interface:

interface GdprSavior {
	restore(shouldUpdate?: boolean): Promise<GdprManager | null>;

	exists(shouldUpdate?: boolean): Promise<boolean>;

	restoreOrCreate(factory: GdprManagerFactory): Promise<GdprManager>;

	store(manager: GdprManagerRaw): Promise<boolean>;

	storeIfNotExists(manager: GdprManagerRaw): Promise<boolean>;

	updateSharedManager(manager: GdprManager): Promise<void>;

	check(): Promise<void>;
}

Events API

This API helps reacting to the user confirming their choices from a GDPR banner.

type GdprManagerEventHandler = () => void;

interface GdprManagerEventHub {
	onEnable(guardName: string, callback: GdprManagerEventHandler): this;

	onDisable(guardName: string, callback: GdprManagerEventHandler): this;

	enable(guardName: string): this;

	disable(guardName: string): this;
}

interface GdprManager {
	bannerWasShown: boolean;
	events: GdprManagerEventHub;

	resetAndShowBanner(): void;

	closeBanner();
}

The goal is to call Manager#closeBanner when the user confirm their choices from the banner, which in turn will trigger the appropriate events (so you can load scripts dynamically for instance).

Visitor API

This API allows you to visit your manager's entire guard tree easily.

interface GdprVisitor {
	onManager(manager: GdprManager): void;

	onGroup(group: GdprGuardGroup): void;

	onGuard(guard: GdprGuard): void;

	onEach(guard: GdprGuard): void;
}

declare function visitGdpr(guard: GdprGuard, visitor?: Partial<GdprVisitor>);

Decorator API

This API allows you to decorate the manager instance that is created or restored when using the Savior API.

As such the Savior API has been extended/augmented with the following:

type GdprManagerDecorator = (manager: GdprManager) => GdprManager;

interface GdprSavior {
	decorate?: GdprManagerDecorator;
}

abstract class GdprSaviorAdapter implements GdprSavior {
	constructor(protected decorator: GdprManagerDecorator|undefined = undefined) {}

	public abstract restore(shouldUpdate?: boolean): Promise<GdprManager | null>;

	public abstract store(manager: GdprManagerRaw): Promise<boolean>;

	public abstract updateSharedManager(manager: GdprManager): Promise<void>;
};

Helpline

If you need any help, you're more than welcome on my official Discord server dedicated to my open-source projects.