save

Persist object data, processing input from HTML or JSON sources.

*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/save
`

@itrocks/save is designed to be used alongside other it.rocks building
blocks such as:

- @itrocks/action
- @itrocks/action-request
- @itrocks/data-to-object
- @itrocks/storage
- @itrocks/auto-redirect

It fits naturally inside a CRUD stack built with
@itrocks/crud-pack.

Usage

@itrocks/save provides a ready‑made backend action that

- receives data from an HTML form or JSON request,
- merges that data into a domain object,
- persists the object using the configured storage engine,
- and returns either an HTML confirmation page or a JSON payload.

You typically extend the generic Save action with your own domain
type and HTTP route.

$3

`ts
// src/domain/user.ts
export class User {
id = 0
name = ''
email = ''
}

// src/actions/user/save-user.ts
import { Save } from '@itrocks/save'
import { Route } from '@itrocks/route'
import type { Request } from '@itrocks/action-request'

import { User } from '../../domain/user.js'

@Route('/users/save')
export class SaveUser extends Save {}

const saveUser = new SaveUser()

// Example of using the action in your HTTP layer
export async function saveUserHtml (request: Request) {
// The request already contains the form data for the user
return saveUser.html(request)
}
`

With a route configuration that converts an incoming HTTP request to a
Request, you can wire an HTML form directly to the /users/save
endpoint:

`html





Save



`

When the form is submitted, SaveUser.html() will

- build or load a User instance from the request,
- apply incoming form fields to that instance,
- persist it via the current storage backend,
- and render a small confirmation page that includes an
auto‑redirect link back to the previous screen.

$3

The same Save action can expose both HTML and JSON persistence
endpoints. This is useful when you want a form‑based UI and a
programmatic API.

`ts
// src/actions/user/save-user.ts
import { Save } from '@itrocks/save'
import { Route } from '@itrocks/route'
import type { Request } from '@itrocks/action-request'

import { User } from '../../domain/user.js'

@Route('/users/save')
export class SaveUser extends Save {}

const saveUser = new SaveUser()

// HTML confirmation + auto‑redirect (uses the default save.html template)
export async function saveUserHtml (request: Request) {
return saveUser.html(request)
}

// JSON response with the saved object
export async function saveUserJson (request: Request) {
return saveUser.json(request)
}
`

Combined with other CRUD actions such as @itrocks/new and
@itrocks/edit, you get a standard flow:

1. Render a form (New or Edit).
2. Submit the form to a Save endpoint.
3. Let Save persist the object and return the appropriate
response (HTML or JSON).

API

$3

The main exported symbol is the generic Save class. It is a
concrete Action implementation, pre‑wired to take incoming data,
apply it to an object of type T, and persist that object.

You typically create a subclass specific to your domain and route
configuration, for example SaveUser extends Save.

#### Type parameter

- T extends object – the domain type you want to save (for example
User, Product, Order, …).

Save instantiates T when saving a new object and reuses the
existing instance when editing, based on the Request it receives.

#### html(request: Request): Promise

Handle an HTML‑oriented save request.

Parameters

- request – a Request describing the current action call. It is
normally created by @itrocks/action-request from an incoming HTTP
request and contains:
- a reference to the target type T,
- an existing object instance when editing,
- the incoming data (typically form fields or query/body parameters).

Behavior

- If the request refers to an existing object, its properties are
updated from the incoming data.
- If there is no existing object, a new instance of T is created and
populated.
- The resulting object is persisted using the configured
@itrocks/storage data source.
- An HTML response is returned. By default this uses the
save.html template shipped with this package, which displays a
simple notification such as {@display} saved. and an
auto‑redirect link back to the previous route.

Returns

- A Promise compatible with @itrocks/core-responses.

Use this method when your client expects an HTML confirmation page
after submitting a form.

#### json(request: Request): Promise

Handle a JSON‑oriented save request.

Parameters

- request – a Request with the same semantics as for html(),
usually created from an HTTP request carrying JSON data.

Behavior

- The object of type T is created or loaded from the request.
- Incoming data is applied to the object.
- The object is persisted using the configured @itrocks/storage
backend.
- A JSON response is returned containing the saved object.

Returns

- A Promise compatible with @itrocks/core-responses.

Use this method when you are building an API endpoint consumed by a
JavaScript frontend or other services.

Typical use cases

- CRUD save endpoint for HTML forms – pair Save with
@itrocks/new and @itrocks/edit so that any object edited through
a form is persisted consistently and confirmed with an HTML page.
- JSON API for create / update – expose Save.json() as a
REST‑style endpoint that accepts JSON payloads and returns the saved
object, for use by single‑page applications or other services.
- Shared library of domain actions – define Save actions
in a reusable package that can be imported by multiple apps, relying
on a consistent persistence and response pattern.
- Standardized persistence behavior – enforce the same
validation/mapping/persistence pipeline for all your objects by
routing every form or JSON update through Save` instead of
duplicating save logic.