Git Product home page Git Product logo

human-logs's Introduction

human-logs

npm version npm downloads Github Actions

๐Ÿ›  A tiny log library that allows you to take events, explanations and solutions and connect them like lego-pieces to create user-friendly logs.

Good log messages increases customer satisfaction, as they work as sort of a guide, helping the user achieve what they wanted to achieve. Good logs minimize the amount of support calls, improve customer satisfaction and trust in your product, ultimately being a win-win for both the creators of software and the users.

Inspired by Vercel's Error design framework, human-logs allows you to take events, explanations and solutions, and connect them like lego-pieces, to create user-friendly logs in a versatile manner.

Focus on understanding the errors.

Features

  • Create consistent, helpful logs that help users fix the problem themselves
  • Build versatile errors by connecting events, explanations and solutions
  • Support for parameters: template variables into the log messages
  • Only 193 lines of code

๐Ÿ’ป Example Usage

We start by defining our events, explanations, and solutions. These will later be used in logs to create user-friendly errors, guiding the users to the right solution.

import { createHumanLogs, event, explanation, solution, createTextFormatter } from "human-logs"

export const notionError = createHumanLogs(
  [
    event("fetching_posts_failed", "fetching posts failed", {
      params: {},
    }),
    explanation(
      "missing_params",
      "the {paramType} `{paramName}` is missing for post with ID `{postId}`, and no fallback was provided",
      {
        params: {
          paramType: "",
          paramName: "",
          postId: "",
        },
      }
    ),
    solution(
      "add_missing_param",
      "add the missing {paramType} on your Notion page",
      {
        params: {},
      }
    ),
    solution(
      "provide_fallback",
      "add a fallback to your parameter definition like this:\n\nurl(`{paramName}`, { fallback: `https://useflytrap.com` })",
      {
        params: {
          paramName: "",
        },
      }
    ),
		solution(
      "add_skip_missing_fields",
      "if you want to skip posts that have missing fields, add `skipMissingFields`: true to your `fetchPosts` call like this: `notionSource.fetchPosts({ skipMissingFields: true })`",
      {
        params: {},
      }
    ),
    solution("open_issue", "open an issue for this on GitHub", {
      params: {},
      actions: [
        {
          text: "Open an issue",
          href: "https://github.com/useflytrap/notion-contentlayer/issues/new",
        },
      ],
    }),
  ],
  {
    formatter: createTextFormatter({
      eventsPrefix: "๐Ÿšง ",
      solutionsPrefix: "๐Ÿ› ๏ธ ",
    }),
  }
)

// You can now use `notionError` to create user-friendly error logs, by connecting events, explanations and solutions like lego-blocks.
const errorLog = notionError([
  "fetching_posts_failed",
  "missing_params",
  "add_missing_param",
  "provide_fallback",
  "add_skip_missing_fields",
], {
  // ๐Ÿ‘‡ these are inferred like magic!
  paramName: 'image',
  paramType: 'Image',
  postId: 'abcd-123',
});

console.log(errorLog.toString())
/* => "๐Ÿšง Fetching posts failed because the Image `image` is missing for post with ID `abcd-123`, and no fallback was provided.

๐Ÿ› ๏ธ Solutions:
1) add the missing Image on your Notion page
2) add a fallback to your parameter definition like this: url(`image`, { fallback: `https://useflytrap.com` })
3) if you want to skip posts that have missing fields, add `skipMissingFields`: true to your `fetchPosts` call like this: `notionSource.fetchPosts({ skipMissingFields: true })`"
*/

Wow! Look at how helpful those errors are. These are errors developers, product end-users and everyone in between could only DREAM OF.

๐Ÿ’ป Development

  • Clone this repository
  • Enable Corepack using corepack enable (use npm i -g corepack for Node.js < 16.10)
  • Install dependencies using pnpm install
  • Run the tests using pnpm dev

License

Made with โค๏ธ in Helsinki

Published under MIT License.

human-logs's People

Contributors

skoshx avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

human-logs's Issues

Solutions and actions are in the wrong order

The correct order would be

Solution 1 Text -> Solution 1 Action Text + Href
Solution 2 Text -> Solution 2 Action Text + Href

Right now it is:

Solution 1 Text -> Solution 2 Text
Solution 1 Action Text + Href -> Solution 2 Action Text + Href

Eg; "If this is wrong, Open an issue. You can configure the options ..., Open an issue (https://github...) or Read the docs (https://docs...)"

Make `addEvents` etc chainable

Would be much more idiomatic to be able to do:

const log = createHumanLog({ ... });
log
  .addEvents(["create_project_failed"])
  .addSolution(["remove_existing_project", "upgrade_subscription"])

Add support for templates

Basically, we could define a template api_unreachable:

{
  api_unreachable: {
    events: 'some_event',
    explanation: 'some_explanation',
    // etc...
  }
}

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.