Release Process & Contributing
Relevant source files
The following files were used as context for generating this wiki page:
The @joindeed/prisma-auth project provides a declarative authorization layer for Prisma, primarily focused on GraphQL environments. Development involves maintaining a set of authorization middlewares and a custom grammar parser for @Auth annotations found in Prisma schema comments. The release process relies on manual versioning combined with automated GitHub Actions for package distribution.
Sources: README.md:3-8, src/index.ts:39-43
Release Workflow
The project follows a specific sequence for publishing new versions to the registry. Developers manage versioning manually before triggering automation.
Publication Steps
- Update Version: You must manually edit the
versionfield in thepackage.jsonfile. - Create GitHub Release: You must create a new release on GitHub.
- Tagging: The GitHub release must include a tag that matches the new version number defined in
package.json. - Automated Publish: Once you create the release, GitHub Actions automatically performs the actual package publication.
Sources: README.md:122-126, package.json:3
Release Flow Diagram
This diagram illustrates the transition from local version management to automated deployment.
The workflow ensures that human oversight occurs at the versioning and release stages, while the deployment is handled by automated CI/CD tools.
Sources: README.md:122-126
Development Environment
Contributing to the project requires Node.js and Yarn. The codebase is written in TypeScript and targets es2019.
Build and Maintenance Scripts
The following table describes the primary scripts available for development and maintenance tasks.
| Script | Command | Purpose |
|---|---|---|
build | yarn clean && tsc | Compiles TypeScript source files into the dist directory. |
clean | rm -rf dist | Removes the previous build output. |
test | jest | Runs the test suite to verify code changes. |
test:cov | jest --coverage | Executes tests and generates a code coverage report. |
rebuild-parser | yarn tspegjs ... | Regenerates the TypeScript parser from the PEG.js grammar file. |
Sources: package.json:6-11, tsconfig.json:3-20
Parser Development
The project uses a custom grammar to parse authorization rules from Prisma comments (e.g., /// @Auth(read: [Owner])). This parser is generated from src/descriptionGrammar.pegjs. If you modify the authorization syntax, you must run the rebuild-parser script to update the generated code in src/generated/parser.ts.
Sources: package.json:11, src/descriptionToRoles.ts:24, src/generated/parser.ts:1-5
System Architecture for Contributors
Contributors working on core features interact with three primary middleware components. These components are initialized via the makeAuthorizationMiddlewares function.
Middleware Components
- Field Constraint Middleware: Enforces authorization on individual model fields.
- Type Constraint Middleware: Enforces authorization on 1-to-1 relation fields.
- List Constraint Middleware: Enforces query constraints on list queries and nested relations.
Sources: src/index.ts:39-43, src/makeFieldConstraintMiddleware.ts:18-20, src/makeTypeConstraintMiddleware.ts:31-33
Dependency and Data Flow
The system processes GraphQL info and context objects to determine if a request is authorized based on the model's @Auth description.
Citations: src/index.ts:11-37, src/descriptionToRoles.ts:18-24, src/makeListConstraintMiddleware.ts:51-62
Testing Standards
All new features or bug fixes must be accompanied by tests. The project utilizes jest for unit and integration testing. Tests are located alongside the source files (e.g., .test.ts files). Contributors should ensure that PrismaSelect logic, especially the mergeDeep function, remains protected against prototype pollution.
Sources: package.json:7, src/select.test.ts:4-60
This documentation covers the essential procedures for releasing updates and contributing to the project's architecture and tooling.
Sources: README.md:128-132