gdpr-guard
v2.4.1
Published
Simple GDPR manager
Downloads
39
Maintainers
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
- gdpr-guard-local A simple local storage adapter for gdpr-guard
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)
andcreateGroup(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.