flora-exception v0.1.9

flora-exception  ·

const FloraAdd = mFx(
    [$Number, $Number], $Number,
    (a, b)=>Add(a, b) as number
)

// OR

const FloraAdd = (a : number, b : number) : number =>{
    return Fx(
        [ [a, $Number], [b, $Number] ], $Number,
        (a, b)=> Add(a, b) as number
    )
}

flora-exception is an exception system for Fauna Query Language built on top of the faunadb-js driver. It provides methods for:

• exception raising,
• typing,
• and exception catching.

Quick start

Install

yarn add flora-exception

Import

import {Flora, mFx, $Number} from "flora-exception";

Compose

const FloraAdd = mFx(
    [$Number, $Number], $Number,
    (a, b)=>Add(a, b) as number
)

Query

const result = await client.query(Flora(
    FloraAdd(2, 2)
));

Flora()

Wrap your query logic with Flora():

• Returns value of query, unless a FloraException was raised.

const result = await db.client.query(Flora(
  Add(2, 2)
));
expect(result).toBe(4);

Raise()

Raise() a FloraException:

• The exception along with a stack trace will be returned.
• In the event of an exception, even without Fx consumers, the FloraExceptionStack will be returned so long as the query is not Aborted.

const result = await db.client.query(Flora(
    If(
      IsString(2),
      2,
      Raise(FloraException())
    )
));
expect(isFloraException(result)).toBe(true);

Fx()

Use Fx() to execute logic with type and exception safety:

• Fx will handle mismatched arg or return types.
• In the event that an arg or a return is a FloraException it will be reraised.

/**
 * Adds two numbers.
 * @param a 
 * @param b 
 * @returns 
 */
const FloraAdd = (a : number, b : number) : number=>{
      return Fx(
          [ [a, $Number], [b, $Number] ], // args with type predicates
          $Number, // return type predicate
          (a, b)=>{ // logic
              return Add(a, b) as number
          }
      ) as number
  }

  const result = await db.client.query(Flora(
      FloraAdd(2, 2)
  ));

 expect(result).toBe(4);

mFx()

Use mFx() to create type and exception safe queries with an abbreviated syntax:

• mFx produces a function that will call Fx to compose your query.
• mFxinfers TypeScript types from your type predicates.

/**
 * Adds two numbers.
 * @param a 
 * @param b 
 * @returns 
 */
const FloraAdd = mFx(
    [$Number, $Number], // arg type predicates
    $Number,  // return type predicate
    (a, b)=>Add(a, b) as number
)

const result = await db.client.query(Flora(
     FloraAdd(2, 2)
));

expect(result).toBe(4);

Types

Types are implemented as predicates which are evaluated against a query expression. Fx provides the most robust method of handling types and type exceptions.

Core types are denoted with $. We recommend composed types follow this standard.

const $Numbers = $Array($Number);

Currently, the following primitive types are available:

• $Number
• $Int
• $UInt8
• $Double
• $String
• $Boolean

Several container types have also been implemented:

• $Array
• $Object
• $Tuple

Container types can be used by wrapping another type predicate:

const $Numbers = $Array($Number);

Members of $Object and $Tuple can be made optional:

const $Player = $Object({
  name : $String,
  wins : $Optional($Number)
});

The $Or type predicate can be used to support an arbitrary number of type alternatives. While the $Any type predicate accepts all types.

const $StringsAndNumbers = $Array($Or($String, $Number));  

How it works

• Flora creates or uses an exisiting FloraCollection to store FloraExceptions raised during a query.
• At the start of a query, Flora creates a document on which the FloraExcpetionStack will be stored.
• During the query, all Raises are pushed to the stack.
• Special consumers Fx and Yield, will handle FloraExceptions in the stack without Aborting the query.
• At the end of the query, a StackError will be compiled from the ExceptionStack reporting on the earliest source of error as well as all errant branches.
• In StrictFlora, an errant query will also be aborted to prevent any changes made from being applied.