@superawesome/permissions
Version:
Fine grained permissions / access control with ownerships & attribute picking, done right.
84 lines (42 loc) • 3.47 kB
Markdown
# SuperAwesome Permissions
* NPM package: `@superawesome/permissions`
* Github: `https://github.com/SuperAwesomeLTD/permissions`
# Features
In lieu of a proper landing page, **SuperAwesome Permissions** features:
- [:left_luggage:](/#) **Controlled Access** to Resources
- [:nail_care:](/#) **Fine Grained** Resource Attributes picking
- [:customs:](/#) Dynamic **Ownership** Rules, hooked to your data layer
- [:performing_arts:](/#) Trivial conversion of **Business Rules for Access Control** to **executing permissions** (and vise versa).
- [:atom:](/#) Straight-forward fusion of [Role-Based Access Control](https://en.wikipedia.org/wiki/Role-based_access_control), [Attribute-Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control) and **Whatever-You-Make-it Access control**
- [:telescope:](/#) Unlimited **Scalability** (lazy & eager ownership evaluation)
- [:wrench:](/#) Easy **Integration** with everything (REST, Graphql, SQL, NoSQL, APIs, Frontend, Games, anything)
- [:shell:](/#) **Zero dependencies** with servers, services & other moving parts
- [:triangular_ruler:](/#) Orthogonal / **Aspect Oriented** philosophy
- [:ticket:](/#) **Permit** is all you need to allow a **user** do an **action** on a **resource**
_(^^ github needed to show icons ^^)_
## Contents
The actual generated docs are at `npm run docs:serve` and **coming soon** at [**SuperAwesome Permissions Documentation**](https://permissions.docs.superawesome.com). Go to the left, at the CompoDocs Nav Bar.
**NOTE: THESE LINKS BREAK ON GITHUB! (^^^ read above ^^^)**
- [Introduction & Glossary](additional-documentation/introduction-&-glossary.html)
- [Basic Usage](additional-documentation/basic-usage.html)
- [Detailed Usage & Examples](additional-documentation/detailed-usage-&-examples.html)
- [Philosophy, Principles & Architecture](additional-documentation/philosophy,-principles-&-architecture.html)
- [Inspiration, Problem and Prior Art](/additional-documentation/inspiration,-problem,-prior-art.html).
- [FAQ, Gotchas & Caveats](additional-documentation/faq,-gotchas-&-caveats.html)
- [Future Roadmap](additional-documentation/future-roadmap.html)
**Note**: We also have [native Nestjs Guard & Decorators](https://github.com/SuperAwesomeLTD/permissions-nestjs) empowering an Orthogonal / Aspect Oriented Architecture.
# Versioning
The project follows [semantic versioning](https://semver.org/) which effectively means a new major version x.0.0 is released for breaking changes, minor 0.x.0 for new features and patch 0.0.x for fixes.
# How to develop
## Code
- Simply do an `npm run test:watch` to develop and test at each change.
- With `npm run build:ts` you get a build of the library at `/dist`.
- With `npm run build` you get a full build of library & docs at `/dist`.
## Documentation
End user docs reside at `src/docs` & `*.md.spec` files:
- With `npm run docs:build` it builds docs at `dist/docs` once.
- With `npm run docs:serve` it serves docs at http://127.0.0.1:8090 in non-watch mode.
- With `npm run docs:watch` it serves docs at http://127.0.0.1:8090 in watch & serve mode.
## Docs generation
All `*.md.spec.ts` files generate equivalent `src/docs/generated/*.generated.md`
**Note**: On watch mode it's sometimes slow to build & serve, especially initially. Just change & save the `*.md.spec.ts` file to trigger generation & also refresh browser if its not refreshing automatically.