Skip to main content
Rail Deck

Rail Deck is being prepared for an invitation-only Alpha. Check current availability

Developer documentation

Saved trains

Build formations, set driving profiles, group functions and assign trains to layouts.

Source 0.1.0 Private source package

How the calls fit together

Read the saved train and its settings before editing. Retain reviewed versions; saving settings does not change or restart a moving train.

JavaScript examples

Supply your configured client. Each call awaits a decoded result; errors pass to your caller. These identifiers and values are fictional. Use selected development records and review every change before running it. Opening this page sends no API requests.

See the complete TypeScript workflow · Explore the Node starter

trainFormations.list

Lists account-owned train formations.

const result = await client.trainFormations.list(
  "account 1",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the train formations.

options · optional
RailDeckRequestControlOptions

Optional filters or request controls shown in the type. The example demonstrates the supplied fields.

Returns Promise<RailDeckTrainFormationListResponse>.

Example evidence: Retained SDK transport fixture.

trainFormations.getFunctionGrouping

Loads the train's complete function grouping for viewing or review.

const result = await client.trainFormations.getFunctionGrouping(
  "23",
  "12",
  {}
);
TypeScript parameters and return type
accountId · required
string

Owning account.

trainFormationId · required
string

Selected train.

options · optional
RailDeckRequestControlOptions

Optional cancellation for retired readers.

Returns Promise<TrainFunctionGrouping>.

Example evidence: Retained SDK transport fixture.

trainFormations.saveFunctionGrouping

Saves one complete, reviewed train grouping without replaying uncertain writes.

const result = await client.trainFormations.saveFunctionGrouping(
  "23",
  "12",
  {
    "expectedRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "groups": [
      {
        "key": "function:8",
        "label": "Short horn",
        "functionIds": [
          "8"
        ]
      }
    ]
  }
);
TypeScript parameters and return type
accountId · required
string

Owning account.

trainFormationId · required
string

Selected train.

input · required
SaveTrainFunctionGrouping

Source revision and desired groups.

Returns Promise<TrainFunctionGrouping>.

Example evidence: Retained SDK transport fixture.

trainFormations.previewDuplication

Reviews every vehicle in a train.

const result = await client.trainFormations.previewDuplication(
  "23",
  "9",
  {}
);
TypeScript parameters and return type
accountId · required
string

Authorised account containing the selected railway records.

id · required
string

Identifier of the explicitly selected record in your authorised development environment.

options · optional
RailDeckRequestControlOptions

Optional filters or request controls shown in the type. The example demonstrates the supplied fields.

Returns Promise<RailDeckTrainDuplicationPreview>.

Example evidence: Retained SDK transport fixture.

trainFormations.duplicate

Atomically copies the complete train and its vehicles.

const result = await client.trainFormations.duplicate(
  "23",
  "9",
  {
    "displayName": "{{fixtureDisplayName}}",
    "expectedSourceRevision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "includeNotes": true,
    "includePhotographs": true
  }
);
TypeScript parameters and return type
accountId · required
string

Authorised account containing the selected railway records.

id · required
string

Identifier of the explicitly selected record in your authorised development environment.

input · required
DuplicateRailDeckTrainInput

The operation input. Use the complete typed shape shown in the example and retain reviewed versions for writes.

Returns Promise<RailDeckTrainFormation>.

Example evidence: Retained SDK transport fixture.

trainFormations.getDrivingSettings

Loads train-owned choices, retaining inheritance instead of copying locomotive settings.

const result = await client.trainFormations.getDrivingSettings(
  "account 1",
  "train 1",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Owning account.

trainFormationId · required
RailDeckIdentifier

Saved train whose settings were opened.

options · optional
RailDeckRequestControlOptions

Optional cancellation.

Returns Promise<RailDeckTrainDrivingSettings>.

Example evidence: Retained SDK transport fixture.

trainFormations.saveDrivingSettings

Saves complete style/handling choices without changing formation members.

const result = await client.trainFormations.saveDrivingSettings(
  "account 1",
  "train 1",
  {
    "expectedRevision": 0,
    "style": {
      "mode": "inherit"
    },
    "handling": {
      "mode": "none"
    }
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Owning account.

trainFormationId · required
RailDeckIdentifier

Saved train being configured.

input · required
SaveRailDeckTrainDrivingSettingsInput

Choices and revision retained when opened.

Returns Promise<RailDeckTrainDrivingSettings>.

Example evidence: Retained SDK transport fixture.

trainFormations.listLayoutAssignments

Lists train formations assigned to one layout.

const result = await client.trainFormations.listLayoutAssignments(
  "account 1",
  "layout 1",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the layout.

layoutId · required
RailDeckIdentifier

Layout whose train formations should be listed.

options · optional
RailDeckRequestControlOptions

Optional filters or request controls shown in the type. The example demonstrates the supplied fields.

Returns Promise<RailDeckLayoutTrainFormationListResponse>.

Example evidence: Retained SDK transport fixture.

trainFormations.create

Creates one account-owned train formation.

const result = await client.trainFormations.create(
  "account 1",
  {
    "displayName": "{{fixtureDisplayName}}",
    "members": [
      {
        "memberType": "locomotive",
        "memberId": "loco-1"
      },
      {
        "memberType": "rolling_stock",
        "memberId": "stock-1",
        "loadState": "laden"
      }
    ]
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that will own the train formation.

input · required
CreateRailDeckTrainFormationInput

Train formation details and optional initial members.

Returns Promise<RailDeckTrainFormation>.

Example evidence: Retained SDK transport fixture.

trainFormations.assignToLayout

Assigns an account train formation to a layout.

const result = await client.trainFormations.assignToLayout(
  "account 1",
  "layout 1",
  {
    "trainFormationId": "formation-2",
    "displayOrder": 2,
    "isActive": true
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the layout and train formation.

layoutId · required
RailDeckIdentifier

Layout receiving the train formation assignment.

input · required
AssignRailDeckTrainFormationToLayoutInput

Train formation id and optional display settings.

Returns Promise<RailDeckLayoutTrainFormation>.

Example evidence: Retained SDK transport fixture.

trainFormations.get

Loads one account-owned train formation.

const result = await client.trainFormations.get(
  "account 1",
  "formation-2",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the train formation.

trainFormationId · required
RailDeckIdentifier

Train formation to load.

options · optional
RailDeckRequestControlOptions

Optional filters or request controls shown in the type. The example demonstrates the supplied fields.

Returns Promise<RailDeckTrainFormation>.

Example evidence: Retained SDK transport fixture.

trainFormations.getHandlingProfile

Loads the advisory handling profile for one train formation.

const result = await client.trainFormations.getHandlingProfile(
  "account 1",
  "formation-2"
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the train formation.

trainFormationId · required
RailDeckIdentifier

Train formation whose handling profile should be loaded.

Returns Promise<RailDeckTrainFormationHandlingProfile>.

Example evidence: Retained SDK transport fixture.

trainFormations.update

Updates one account-owned train formation.

const result = await client.trainFormations.update(
  "account 1",
  "formation-2",
  {
    "displayName": "{{fixtureDisplayName}}",
    "expectedUpdatedAt": "2026-07-02T09:00:00.000Z"
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the train formation.

trainFormationId · required
RailDeckIdentifier

Train formation to update.

input · required
UpdateRailDeckTrainFormationInput

Changed fields and the updatedAt version retained when opened.

Returns Promise<RailDeckTrainFormation>.

Example evidence: Retained SDK transport fixture.

trainFormations.updateLayoutAssignment

Updates display state for a train formation assigned to a layout.

const result = await client.trainFormations.updateLayoutAssignment(
  "account 1",
  "layout 1",
  "formation-2",
  {
    "isActive": false
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the layout and train formation.

layoutId · required
RailDeckIdentifier

Layout containing the assignment.

trainFormationId · required
RailDeckIdentifier

Train formation assignment to update.

input · required
UpdateRailDeckLayoutTrainFormationInput

Partial layout assignment update.

Returns Promise<RailDeckLayoutTrainFormation>.

Example evidence: Retained SDK transport fixture.

trainFormations.replaceMembers

Replaces all ordered members for one train formation.

const result = await client.trainFormations.replaceMembers(
  "account 1",
  "formation-2",
  {
    "expectedUpdatedAt": "2026-07-02T09:00:00.000Z",
    "members": [
      {
        "memberType": "locomotive",
        "memberId": "loco-1",
        "displayOrder": 0
      }
    ]
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the train formation.

trainFormationId · required
RailDeckIdentifier

Train formation receiving replacement members.

input · required
ReplaceRailDeckTrainFormationMembersInput

Complete replacement members and the updatedAt version retained when opened.

Returns Promise<RailDeckTrainFormation>.

Example evidence: Retained SDK transport fixture.

trainFormations.delete

Deletes one account-owned train formation.

const result = await client.trainFormations.delete(
  "account 1",
  "formation-2",
  {
    "expectedUpdatedAt": "2026-07-02T09:00:00.000Z"
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the train formation.

trainFormationId · required
RailDeckIdentifier

Train formation to delete.

input · required
DeleteRailDeckTrainFormationInput

The updatedAt version reviewed before deletion.

Returns Promise<RailDeckSuccessResponse>.

Example evidence: Retained SDK transport fixture.

trainFormations.removeFromLayout

Removes one train formation assignment from a layout.

const result = await client.trainFormations.removeFromLayout(
  "account 1",
  "layout 1",
  "formation-2"
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the layout and train formation.

layoutId · required
RailDeckIdentifier

Layout containing the assignment.

trainFormationId · required
RailDeckIdentifier

Train formation assignment to remove.

Returns Promise<RailDeckSuccessResponse>.

Example evidence: Retained SDK transport fixture.

Download all TypeScript method examples

JavaScript calls and TypeScript downloads are checked through the real SDK using local response fixtures. This verifies the calls and decoding for those fixtures.

Handle errors and uncertain outcomes

Choose another feature

The complete TypeScript workflow

Follow how the calls fit together, including the review and recovery steps. Supply your configured client and explicitly selected development records. Importing the download performs no requests; mutations are never retried automatically.

import type { RailDeckDirectIntegrationClient as Client } from '@raildeck/frontend-sdk/direct-integration';

/**
 * Read a formation and its driving settings for review.
 * @param client - Configured client; the caller owns current authority.
 * @param accountId - Authorised account for this workflow.
 * @param trainId - Explicitly selected saved train.
 * @param signal - Caller-owned cancellation signal.
 * @returns The saved train and original settings revision.
 */
export async function openSavedTrain(
  client: Client,
  accountId: string,
  trainId: string,
  signal: AbortSignal,
) {
  const options = { signal, timeoutMs: 15_000 };
  const train = await client.trainFormations.get(accountId, trainId, options);
  const settings = await client.trainFormations.getDrivingSettings(accountId, trainId, options);
  return { train, settings };
}

/**
 * Change a confirmed saved style while retaining reviewed handling and revision.
 * @param client - Configured client; the caller owns current authority.
 * @param accountId - Authorised account for this workflow.
 * @param trainId - Explicitly selected saved train.
 * @param opened - Record retained from the review that authorised this change.
 * @param style - Driving style explicitly chosen for the saved train.
 * @returns Saved settings; saving them does not restart a moving train.
 */
export async function saveReviewedTrainStyle(
  client: Client,
  accountId: string,
  trainId: string,
  opened: Awaited<ReturnType<Client['trainFormations']['getDrivingSettings']>>,
  style: Parameters<Client['trainFormations']['saveDrivingSettings']>[2]['style'],
) {
  return client.trainFormations.saveDrivingSettings(accountId, trainId, {
    expectedRevision: opened.revision, style, handling: opened.handling,
  });
}
Download TypeScript example

Related information

Information reviewed .