@jaypie/core v1.0.29

Jaypie Core 🐦‍⬛🥧

Utility package with constants, errors, functions and logging

🐦‍⬛ Introduction

Jaypie is an opinionated approach to application development centered around JavaScript and the JSON:API specification in an event-driven architecture

Beyond that Jaypie core tries to stay neutral. Jaypie libraries such as @jaypie/express build off of this core into specific ecosystems

In an ideal world the bird would be looking at the pie

📋 Usage

Installation

npm install @jaypie/core

Example

Simple Example Using Lambda

event is passed to the handler when the event is triggered. It will include details about the event (e.g., type, parameters).

import { lambdaHandler, log } from "@jaypie/core";

export default lambdaHandler(
  // Handler function
  async (event) => {
    log.trace("\"Happy path\" events belong in trace");

    // "Your Code Here"

    return "Hello, world!";
  },
  // Configuration (optional)
  {
    name: "helloWorld",
  },
);

Throw jaypie errors below to convey semantic meaning. Thrown errors will be caught and logged. Non-jaypie errors will be treated as unhandled exceptions. Log your own errors with log.error.

import { log, NotFoundError } from "@jaypie/core";

log.error("Could not find resource");
throw NotFoundError();

Simple Logging

log.trace("\"Happy path\" events belong in trace");

// Important variables for debugging can be logged as "var"s
log.var("message", "Hello, world");
log.var({ message: "Hello, world" });
log.var({ message });

if(event.strangeCondition) {
  log.debug("Slight deviation from the happy path");
  // ...Helpful for someone debugging a real problem later
}

if(event.problemCondition) {
  log.warn("Someone should look into this");
  // ...It can at least be tracked to know how often it happens
}

if(event.errorCondition) {
  log.error("Something is not right!");
  // ...It might even be broken
}

log functions should be used in your logic. Following the "trace-only happy path" will simplify debugging and log management.

log.info exists for things that should be tracked external to debugging (e.g., transaction successes). By default the event and the response from the handler will be logged as info. This should be the least-used log level by code references (we hope error and warn are unused in runtime)

Complex Example Using Express

import { expressHandler, log } from "@jaypie/core";

export default expressHandler(
  // Handler function
  async ({ req }) => {
    log.trace("\"Happy path\" events belong in trace");

    // "Your Code Here"

    return json;
  },
  // Configuration (optional)
  {
    name: "expressApi",
    validate: [], // Array of validation functions
    setup: [], // Array of setup functions
    local: [], // Array of local values and getters
    teardown: [], // Array of teardown functions
  },
);

The function:

• Only receives req and it must be destructured
• Should return a JSON object, ideally JSON:API-compliant 🤩
• May return a scalar which will be treated as text/html
• Should throw a jaypie error if there is a problem

TODO: This example needs specifics on validate, setup, local, and teardown

📖 Reference

Constants

TODO: Complete list of constants in the package

Errors

TODO: Complete list of errors in the package

Functions

TODO: Complete list of utility functions in the package

Handlers

TODO: Complete list of utility functions in the package

Logging

import { 
  log,
  LOG, // LOG.FORMAT, LOG.LEVEL
} from "@jaypie/core";

log

import { log } from "@jaypie/core";

log.trace();
log.debug();
log.info();
log.warn();
log.error();
log.fatal();

log.lib({ lib: "myLib" })

Uses silent by default. if process.env.MODULE_LOG_LEVEL is true, follows process.env.LOG_LEVEL. If process.env.MODULE_LOG_LEVEL is also set, uses that log level.

import { log } from "@jaypie/core";

log.lib().trace();
log.lib({ lib: "myLib" }).trace();

log.var(key, value) or log.var({ key: value })

Log a key-value pair. In the json format, the key will be tagged as var and the value will be the value. Logging marker variables this way can be useful for debugging.

import { log } from "@jaypie/core";

log.var("message", "Hello, world");
log.var({ message: "Hello, world" });

const message = "Hello, world";
log.var({ message });

log.with() - clone

Create a new log object with additional tags

import { log as defaultLogger } from "@jaypie/core";

const log = defaultLogger.with({ customProperty: "customValue" });

🌠 Wishlist

• Complete documentation

📝 Changelog

📜 License

Published by Finlayson Studio. All rights reserved