@itrocks/signup
Version:
Handles user sign-up for @itrocks/user, with account creation and secure onboarding flow
177 lines (135 loc) • 7.27 kB
Markdown
[](https://www.npmjs.org/package/@itrocks/signup)
[](https://www.npmjs.org/package/@itrocks/signup)
[](https://github.com/itrocks-ts/signup)
[](https://github.com/itrocks-ts/signup/issues)
[](https://25.re/ditr)
# signup
Handles user sign-up for @itrocks/user, with account creation and secure onboarding flow.
*This documentation was written by an artificial intelligence and may contain errors or approximations.
It has not yet been fully reviewed by a human. If anything seems unclear or incomplete,
please feel free to contact the author of this package.*
## Installation
```bash
npm i @itrocks/signup
```
`@itrocks/signup` is designed to plug into the it.rocks action and routing
stack. It is usually installed alongside `@itrocks/user`, `@itrocks/action`,
and the rest of the it.rocks back‑end packages, but you can also use it in a
custom Node.js / TypeScript application that already relies on it.rocks
infrastructure.
## Usage
`@itrocks/signup` provides a specialised `Signup` action that implements a
complete HTML sign‑up flow for your `User` entity:
- renders a sign‑up form when accessed with no POST data,
- validates the submitted fields (`email`, `login`, `password`),
- checks that the email or login is not already used by another user,
- creates and persists the new user when everything is valid,
- displays either a success page or an error page when something is wrong.
The action is tied to the `/user/signup` route through the provided
`config.yaml` file, so once the package is loaded by the it.rocks framework
you automatically get a working sign‑up endpoint.
### Minimal example
In a typical it.rocks project you do not instantiate `Signup` yourself: the
framework wires it based on configuration. The following example shows how you
would use it manually in a custom setup to better understand the API.
```ts
import { Signup } from '@itrocks/signup'
import { toActionRequest } from '@itrocks/action-request'
import type { Request } from '@itrocks/action-request'
import type { User } from '@itrocks/user'
// Create an action instance bound to your User type
const signup = new Signup<User>()
// Example HTML endpoint in an HTTP framework such as Fastify
async function signupHtml (req: any, reply: any) {
const request: Request<User> = toActionRequest<User>(req)
const response = await signup.html(request)
reply
.status(response.status)
.headers(response.headers)
.type('text/html')
.send(response.body)
}
```
The action takes care of:
- creating a new `User` instance,
- binding request data to the instance,
- querying your configured data source to detect duplicates,
- saving the user when the credentials are unique,
- choosing the right template (`signup.html`, `signup-error.html`,
`registered.html`).
### Complete example with routing and configuration
When used inside a full it.rocks stack, you usually rely on routing and
configuration instead of wiring everything manually.
1. Install the package and ensure your application loads
`node_modules/@itrocks/signup/config.yaml` together with other
configuration files.
2. Configure your `User` class in `@itrocks/user` (email, login, password
fields, storage, etc.).
3. Start your HTTP server with the it.rocks router enabled.
4. Visit `/user/signup` in a browser.
Behaviour:
- On first GET, the action returns the `signup` HTML form.
- On POST with empty or incomplete credentials, it re‑displays the form
through the `signup-error` template.
- On POST with credentials that conflict with an existing user (same email or
login, or email/login swapped), it also displays the `signup-error` template
and exposes the found user instance to the view layer.
- On POST with valid and unique credentials, it saves the new user and
renders the `registered` confirmation page.
Your front‑end templates (`signup.html`, `signup-error.html`,
`registered.html`) are shipped with the package and can be customised at the
project level if needed, following the standard it.rocks theming rules.
## API
### `class Signup<T extends User = User> extends Action<T>`
Specialised action that handles the whole sign‑up lifecycle for a `User`
entity: presenting the form, validating input, checking duplicates and
persisting the user.
The class is generic so you can pass a custom user subclass if your project
extends `@itrocks/user` with additional fields.
#### Type parameter
- `T extends User = User` – the concrete user entity type handled by the
action. By default it is the base `User` class from `@itrocks/user`, but you
can pass any subclass that adds extra profile / domain‑specific fields.
#### Methods
##### `html(request: Request<T>): Promise<HtmlResponse>`
Builds an HTML response for the sign‑up flow.
Pipeline:
1. Creates a new user instance of `request.type`.
2. If the request contains form data, copies it onto the user using
`@itrocks/data-to-object`.
3. Validates that `email`, `login` and `password` are non‑empty.
4. Uses the configured data source (`@itrocks/storage`) to search for an
existing user with:
- same email,
- same login,
- email used as login,
- login used as email.
5. Depending on the outcome:
- if a duplicate is found, renders the `signup-error` template and exposes
the found user;
- if everything is valid and unique, saves the new user and renders the
`registered` template;
- otherwise, renders the `signup-error` template for missing fields.
6. Returns an `HtmlResponse` built with `htmlTemplateResponse`, pointing to
the selected HTML template.
Parameters:
- `request: Request<T>` – it.rocks action request describing the current HTTP
call (method, path, data, user type, etc.). Usually created from an
incoming HTTP request by `@itrocks/action-request`.
Return value:
- `Promise<HtmlResponse>` – response object from
`@itrocks/core-responses` containing status, headers and rendered HTML
body.
## Typical use cases
- **Public sign‑up page for web applications** – expose `/user/signup` so
visitors can create their own account that is stored through
`@itrocks/user` and `@itrocks/storage`.
- **Onboarding flow in a portal** – integrate the sign‑up form into a wider
onboarding sequence (email verification, profile completion, terms
acceptance) while keeping user creation logic in a single action.
- **Reuse in multiple projects** – share the same sign‑up logic across
several back‑end services or customer‑facing applications by plugging the
`Signup` action into each project configuration.
- **Custom user models** – derive your own `Customer` or `Member` class from
`User` and use `Signup<Customer>` so that additional fields (company,
locale, marketing preferences, …) are captured at registration time.