@dupkey/payload
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.5 • Public • Published

    @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.

    Install

    npm i @dupkey/payload

    DownloadsWeekly Downloads

    6

    Version

    1.0.5

    License

    MIT

    Unpacked Size

    15 kB

    Total Files

    13

    Last publish

    Collaborators

    • nicgene