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

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.

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.