@dupkey/payload

A data transfer object to send domain-layer results to your application.

This is ported from a PHP library named Aura.Payload. As this contains a substantial portions of the software; license included. For more information check out the Aura.Payload docs.

Install

npm install @dupkey/payload

Example

import Password from '@dupkey/password';
import { Payload, PayloadInterface, PayloadStatus } from '@dupkey/payload';
import Uuid from '@dupkey/uuid';
import UserEntity from './UserEntity';
import UserMessage from './UserMessage';
import UserRepository from './UserRepository';
import UserValidator from './UserValidator';

export default class UserService {
  private userMessage: UserMessage;
  private userRepository: UserRepository;
  private userValidator: UserValidator;

  constructor(userMessage: UserMessage, userRepository: UserRepository, userValidator: UserValidator) {
    this.userMessage = userMessage;
    this.userRepository = userRepository;
    this.userValidator = userValidator;
  }

  public async create(name: string, email: string, password: string): Promise<PayloadInterface> {
    let payload = (new Payload()).setInput({ name, email, password });

    if (this.userValidator.forCreate(name, email, password) === false) {
      return payload.setStatus(PayloadStatus.NOT_VALID)
        .setErrors(this.userValidator.getErrors());
    }

    let user = await this.userRepository.fetchOneByEmail(email);
    if (user !== null) {
      if (user.getBanned() === null) {
        await this.userMessage.forExists(user);
      }

      // Do not divulge that the username exists in our system
      return payload.setStatus(PayloadStatus.CREATED)
        .setOutput(new UserEntity(Uuid.v4(), name, email, await hash(password, 10), new Date()));
    }

    user = new UserEntity(
      Uuid.v4(),
      name,
      email,
      await hash(password, 10),
      new Date()
    );

    await this.userRepository.save(user);
    await this.userMessage.forCreate(user);

    return payload.setStatus(PayloadStatus.CREATED).setOutput(user);

  }
}

Methods

Use these methods in your domain layer to modify the Payload. (All set*() methods return the Payload object itself, so you can chain the methods fluently.)

• setStatus(status: PayloadStatus): Payload: Sets the payload status in terms of the domain layer.

• setInput(input: any): Payload: Sets the input as received by the domain layer.

• setOutput(output: any): Payload: Sets the output produced by the domain layer.

• setMessages(messages: { title: string, detail?: string, source: string[] }[]): Payload: Sets the messages reported by the domain layer.

• setErrors(messages: { title: string, detail?: string, source: string[] }[]): Payload: Sets the messages reported by the domain layer.

• setExtras(extras: any): Payload: Sets "extra" values produced by the domain layer.

Your calling code can then examine the payload object using the get*() complements to the the set*() methods.

• getStatus(): PayloadStatus | undefined: Gets the payload status in terms of the domain layer.

• getInput(): any: Gets the input as received by the domain layer.

• getOutput(): any: Gets the output produced by the domain layer.

• getMessages(): { title: string, detail?: string, source: string[] }[]: Gets the messages reported by the domain layer.

• getErrors(): { title: string, detail?: string, source: string[] }[]: Gets the errors reported by the domain layer.

• getExtras(): any: Gets "extra" values produced by the domain layer.

Status Values

Several generic status values are available as constants on the PayloadStatus class:

• PayloadStatus.ACCEPTED: A command has been accepted for later processing.
• PayloadStatus.AUTHENTICATED: An authentication attempt succeeded.
• PayloadStatus.AUTHORIZED: An authorization request succeeded.
• PayloadStatus.CREATED: A creation attempt succeeded.
• PayloadStatus.DELETED: A deletion attempt succeeded.
• PayloadStatus.ERROR: There was a major error of some sort.
• PayloadStatus.FAILURE: There was a generic failure of some sort.
• PayloadStatus.FOUND: A query successfullly returned results.
• PayloadStatus.NOT_ACCEPTED: A command failed to be accepted.
• PayloadStatus.NOT_AUTHENTICATED: The user is not authenticated.
• PayloadStatus.NOT_AUTHORIZED: The user is not authorized for the action.
• PayloadStatus.NOT_CREATED: A creation attempt failed.
• PayloadStatus.NOT_DELETED: A deletion attempt failed.
• PayloadStatus.NOT_FOUND: A query failed to return results.
• PayloadStatus.NOT_UPDATED: An update attempt failed.
• PayloadStatus.NOT_VALID: User input was invalid.
• PayloadStatus.PROCESSING: A command is in-process but not finished.
• PayloadStatus.SUCCESS: There was a generic success of some sort.
• PayloadStatus.UPDATED: An update attempt succeeded.
• PayloadStatus.VALID: User input was valid.

Build the TypeScript and JavaScript versions

npm run build

Run the tests

npm test

VS Code Debugging

Create a launch.json file in your .vscode folder with the following:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Mocha Tests",
      "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
      "args": [
        "--require", "ts-node/register",
        "-u", "tdd",
        "--timeout", "999999",
        "--colors", "--recursive",
        "${workspaceFolder}/test/**/*.ts"
      ],
      "internalConsoleOptions": "openOnSessionStart"
    }
  ]
}

In the debug tab (Ctrl+Shift+D) select "Mocha Tests" from the dropdown and then click "Start Debugging". Results will display in the console on the bottom of the VS Code.