{"id":20494309,"url":"https://github.com/voltra/gdpr-guard","last_synced_at":"2025-04-13T17:21:41.836Z","repository":{"id":44377628,"uuid":"231287402","full_name":"Voltra/gdpr-guard","owner":"Voltra","description":"Simple GDPR manager","archived":false,"fork":false,"pushed_at":"2024-07-06T11:39:29.000Z","size":1113,"stargazers_count":5,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T01:49:11.643Z","etag":null,"topics":["front-end","frontend","gdpr","gdpr-guard","hacktoberfest","javascript-library","typescript-definitions","typescript-library"],"latest_commit_sha":null,"homepage":"https://voltra.github.io/gdpr-guard","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Voltra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-02T01:41:19.000Z","updated_at":"2024-07-06T11:39:05.000Z","dependencies_parsed_at":"2023-12-05T16:09:51.256Z","dependency_job_id":"6d6bfa53-7a4c-4030-9ee8-e22b679a1d22","html_url":"https://github.com/Voltra/gdpr-guard","commit_stats":{"total_commits":78,"total_committers":2,"mean_commits":39.0,"dds":0.02564102564102566,"last_synced_commit":"413b053321b3eea940a1328ccfd025841d67926d"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2Fgdpr-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2Fgdpr-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2Fgdpr-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2Fgdpr-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Voltra","download_url":"https://codeload.github.com/Voltra/gdpr-guard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248750853,"owners_count":21155795,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["front-end","frontend","gdpr","gdpr-guard","hacktoberfest","javascript-library","typescript-definitions","typescript-library"],"created_at":"2024-11-15T17:39:04.236Z","updated_at":"2025-04-13T17:21:41.813Z","avatar_url":"https://github.com/Voltra.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gdpr-guard\n\n\u003e Simple GDPR manager\n\n\u003ccenter\u003e\u003cimg src=\"https://github.com/Voltra/gdpr-guard/raw/master/gdpr-guard.png\" alt=\"Logo\" width=\"250px\"/\u003e\u003c/center\u003e\n\nThis library helps you build a GPDR compliant system by providing you easy to manipulate interfaces.\n\n## Eco-system\n\nThere are a handful of libraries to help you along the way:\n* binding libraries, which ease the use with your favorite frameworks \u0026 libraries\n* persistence libraries, which offer you storage/persistence solutions\n\n## Bindings\n\n* [html-gdpr-guard](https://www.npmjs.com/package/html-gdpr-guard) Use `gdpr-guard` as efficiently and easily as possible, based on data provided in the DOM\n* [dom-gdpr-guard](https://www.npmjs.com/package/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)\n* [vue-gdpr-guard](https://www.npmjs.com/package/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)\n* [vue3-gdpr-guard](https://www.npmjs.com/package/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\n* [react-gdpr-guard](https://www.npmjs.com/package/react-gdpr-guard) A React library that provides a hooks-creating function to interact with your GdprManager, in a react-way\n* [ngx-gdpr-guard](https://www.npmjs.com/package/ngx-gdpr-guard) An Angular library that exposes a module and service to interact with your GdprManager, in an Angular and RXjs way\n* [svelte-gdpr-guard](#) ***Coming Soon***\n* [rx-gdpr-guard](#) ***Coming Soon***\n\n## Persistence\n\n* [gdpr-guard-local](https://www.npmjs.com/package/gdpr-guard-local) A simple local storage adapter for gdpr-guard\n\n## How to import\n\nUsing ES6-style imports:\n\n```javascript\nimport {\n\t//most useful\n\tGdprStorage,\n\tGdprManagerBuilder,\n\tGdprDeserializer,\n\n\t//helpers\n\tmakeGuard,\n\tvisitGdpr,\n\tGdprGuardGroup,\n\tGdprManager,\n\tGdprSerializer,\n\tGdprSaviorAdapter,\n} from \"gdpr-guard\"\n```\n\nUsing node style require:\n\n```javascript\nconst {\n\t//most useful\n\tGdprStorage,\n\tGdprManagerBuilder,\n\tGdprDeserializer,\n\n\t//helpers\n\tmakeGuard,\n\tvisitGdpr,\n\tGdprGuardGroup,\n\tGdprManager,\n\tGdprSerializer,\n\tGdprSaviorAdapter,\n} = require(\"gdpr-guard\");\n```\n\nDirectly from your browser:\n\n```javascript\nconst {\n\t//most useful\n\tGdprStorage,\n\tGdprManagerBuilder,\n\tGdprDeserializer,\n\n\t//helpers\n\tmakeGuard,\n\tvisitGdpr,\n\tGdprGuardGroup,\n\tGdprManager,\n\tGdprSerializer,\n\tGdprSaviorAdapter,\n} = gdprGuard;\n```\n\n## What are the essential design choices to keep in mind\n\nThe `name` used for guards and groups ***must*** be unique! This is the identifier/key that binds it.\n\nThe wide concept of `guard` is that a `guard` is an entity that can be toggled to allow/deny some functionalities.\n\n## What is provided?\n\nYou can check the [documentations here](https://voltra.github.io/gdpr-guard/)\n\n### GdprStorage\n\nThis is an enum-like type that lists the available storage options, these include:\n\n* None\n* Cookie\n* LocalStorage\n* SessionStorage\n* IndexedDb\n* FileSystem\n* ServerStorage\n* All\n\n### GdprManagerBuilder\n\n`GdprManagerBuilder` provides a nice and easy to write/read way to create a `GdprManager` object from the groun up.\n\nFor instance you can use it like this:\n\n```javascript\nconst manager = GdprManagerBuilder\n\t.make()\n\t\t.startRequiredGroup(GdprStorage.Cookie, \"Functionalities\", \"Information purely used for the user's experience\")\n\t\t// This is a group that by default uses cookies for storage, every option and the group itself is required\n\t\t\t.withEnabledGuard(\"PHP_SESSID\", \"Server session identifier\")\n\t\t\t.startGuard()\n\t\t\t\t.withName(\"theme\")\n\t\t\t\t.withDescription(\"User's current colors' theme\")\n\t\t\t\t.storedIn(GdprStorage.LocalStorage)\n\t\t\t.endGuard()\n\t\t.endGroup()\n\t\t.startGroup(GdprStorage.Cookie, \"Advertisement\", \"Tracking-based avertisement informations\")\n\t\t\t.startGroup(GdprStorage.Cookie, \"Advertisement : Local\", \"Sitewide advertisement informations\")\n\t\t\t// [...]\n\t\t\t.endGroup()\n\t\t\t.startGroup(GdprStorage.Cookie, \"Advertisement : 3rd-party\", \"3rd-party advertisement informations\")\n\t\t\t// [...]\n\t\t\t.endGroup()\n\t\t.endGroup()\n\t.build();\n\nconsole.log(manager.raw()); // inspect useful information\n```\n\n### GdprDeserializer\n\n`GdprDeserializer` allows you to retrieve a gdpr object from its `raw` representation.\n\n```javascript\nimport { GdprManagerBuilder, GdprDeserializer } from \"gdpr-guard\"\n\n// [...]\n\nconst manager = GdprManagerBuilder.make()\n\t// [...]\n\t.build();\n\nconst raw = manager.raw();\n//store in local storage\n\nconst raw = //get from local storage\nconst manager = GdprDeserializer.manager(raw);\nif (manager === null) { //failed deserialization\n\t//handle error\n\treturn;\n}\n\n// here, both managers are equivalent\n```\n\n### GdprManager\n\nA `GdprManager` manages a list of `GdprGuardGroup`. You can :\n\n* get its most useful representation (`raw()`)\n* add or create groups (respectively `addGroup(guardGroup)` and `createGroup(name, description)`)\n* determine whether or not there is a specific guard (`hasGuard(name)`)\n* retrieve a specific guard (`getGuard(name)`)\n* determine whether or not there is a specific group (`hasGroup(name)`)\n* get a specific group (`getGroup(name)`)\n* determine if a guard/group is enabled (`isEnabled(name)`)\n* enable everything except required (`enable()`)\n* disable everything except required (`disable()`)\n* toggle state, i.e. either enable all or disable all (`toggle()`)\n* enable everything for a given storage (`enableForStorage(gdprStorage)`)\n* disable everything for a given storage (`disableForStorage(gdprStorage)`)\n* toggle state for a given storage (`toggleForStorage(gdprStorage)`)\n\n### GdprGuardGroup\n\nA `GdprGuardGroup` manages a list of `GdprGuard` (which includes raw guards, `GdprGuardGroup` and `GdprManager` although\none would not recommend to put managers inside managers).\n\nYou can:\n\n* mark it as required, with every of its guards (`makeRequired()`)\n* get its most useful representation (`raw()`)\n* determine whether or not there is a specific guard (`hasGuard(name)`)\n* retrieve a specific guard (`getGuard(name)`)\n* determine if a guard/group is enabled (`isEnabled(name)`)\n* enable everything except required (`enable()`)\n* disable everything except required (`disable()`)\n* toggle state, i.e. either enable all or disable all (`toggle()`)\n* enable everything for a given storage (`enableForStorage(gdprStorage)`)\n* disable everything for a given storage (`disableForStorage(gdprStorage)`)\n* toggle state for a given storage (`toggleForStorage(gdprStorage)`)\n\n### makeGuard\n\n`makeGuard` is a function that creates the simplest guard possible, it has the following signature:\n\n```typescript\ndeclare function makeGuard(name: string, description: string, storage?: GdprStorage, required?: boolean, enabled?: boolean | null): GdprGuard;\n```\n\n### GdprSaviorAdapter\n\nA class that implements most of the behavior for the Savior API.\n\n```typescript\nabstract class GdprSaviorAdapter implements GdprSavior {\n\tpublic abstract restore(shouldUpdate?: boolean): Promise\u003cGdprManager | null\u003e;\n\n\tpublic abstract store(manager: GdprManagerRaw): Promise\u003cboolean\u003e;\n\n\tpublic abstract updateSharedManager(manager: GdprManager): Promise\u003cvoid\u003e;\n}\n```\n\n## Savior API\n\nThis API helps saving and restoring the manager state. It is exposed mainly for library authors as it helps creating\nvarious bindings for frameworks.\n\nThis is the interface:\n\n```typescript\ninterface GdprSavior {\n\trestore(shouldUpdate?: boolean): Promise\u003cGdprManager | null\u003e;\n\n\texists(shouldUpdate?: boolean): Promise\u003cboolean\u003e;\n\n\trestoreOrCreate(factory: GdprManagerFactory): Promise\u003cGdprManager\u003e;\n\n\tstore(manager: GdprManagerRaw): Promise\u003cboolean\u003e;\n\n\tstoreIfNotExists(manager: GdprManagerRaw): Promise\u003cboolean\u003e;\n\n\tupdateSharedManager(manager: GdprManager): Promise\u003cvoid\u003e;\n\n\tcheck(): Promise\u003cvoid\u003e;\n}\n```\n\n## Events API\n\nThis API helps reacting to the user confirming their choices from a GDPR banner.\n\n```typescript\ntype GdprManagerEventHandler = () =\u003e void;\n\ninterface GdprManagerEventHub {\n\tonEnable(guardName: string, callback: GdprManagerEventHandler): this;\n\n\tonDisable(guardName: string, callback: GdprManagerEventHandler): this;\n\n\tenable(guardName: string): this;\n\n\tdisable(guardName: string): this;\n}\n\ninterface GdprManager {\n\tbannerWasShown: boolean;\n\tevents: GdprManagerEventHub;\n\n\tresetAndShowBanner(): void;\n\n\tcloseBanner();\n}\n```\n\nThe goal is to call `Manager#closeBanner` when the user confirm their choices from the banner, which in turn will\ntrigger the appropriate events (so you can load scripts dynamically for instance).\n\n## Visitor API\n\nThis API allows you to visit your manager's entire guard tree easily.\n\n```typescript\ninterface GdprVisitor {\n\tonManager(manager: GdprManager): void;\n\n\tonGroup(group: GdprGuardGroup): void;\n\n\tonGuard(guard: GdprGuard): void;\n\n\tonEach(guard: GdprGuard): void;\n}\n\ndeclare function visitGdpr(guard: GdprGuard, visitor?: Partial\u003cGdprVisitor\u003e);\n```\n\n## Decorator API\n\nThis API allows you to [decorate](https://en.wikipedia.org/wiki/Decorator_pattern) the manager instance that is created or restored when using the Savior API.\n\nAs such the Savior API has been extended/augmented with the following:\n\n```typescript\ntype GdprManagerDecorator = (manager: GdprManager) =\u003e GdprManager;\n\ninterface GdprSavior {\n\tdecorate?: GdprManagerDecorator;\n}\n\nabstract class GdprSaviorAdapter implements GdprSavior {\n\tconstructor(protected decorator: GdprManagerDecorator|undefined = undefined) {}\n\n\tpublic abstract restore(shouldUpdate?: boolean): Promise\u003cGdprManager | null\u003e;\n\n\tpublic abstract store(manager: GdprManagerRaw): Promise\u003cboolean\u003e;\n\n\tpublic abstract updateSharedManager(manager: GdprManager): Promise\u003cvoid\u003e;\n};\n```\n\n## Helpline\n\nIf you need any help, you're more than welcome on my [official Discord server](https://discordapp.com/invite/JtWAjbw)\ndedicated to my open-source projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltra%2Fgdpr-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoltra%2Fgdpr-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltra%2Fgdpr-guard/lists"}