@enio.ai/path-schema NPM

News

2023-02-11 - First release (beta) :tada:.

Key Features

Model your no-sql database schema with ease using a simple, human-readable syntax. This will help you move away from maintaining cluttered code with constant variables and enums to manage your database paths.
Built-in syntax validation ensures your database schema is always in check.
Get autogenerated TypeScript interfaces for your database references to enjoy intellisense.
Read paths and hydrate dynamic values with .pathWithKeys().

This library was designed with Firebase database use cases in mind.

We've got even more in store for you - support for database schemas with circular references and a CLI version of getDefinitions() and config file are in the works.

Status: Beta :alembic:

This project is in "beta" release, which means; it's all new and needs feedback from the community to improve it further. It's all new and mostly solves our use case to map firebase database paths neatly.

If you find this project useful and want to see more projects like this, consider signing up for support. You can find details are at the very end. :point_down: :seedling:

Installation

Using npm:

$ npm i -g npm
$ npm i --save @enio.ai/path-schema

How to Use

You can import utils from path-schema just as you would with other npm packages.

import { getPaths } from '@enio.ai/path-schema'

Overview

API

Database Schema

To get started, you need to write your database schema as a string. Each line in the string represents a node in your schema, and the relationships between nodes are defined using the » symbol. For example:

@root » #opensource #enterprise
#opensource » #projects
#enterprise » #projects
#projects » #badges
#badges » #coverageBadge #buildBadge
#coverageBadge
#buildBadge

In this example, the @root node is the root of the database, and it has two children, #opensource and #enterprise. The #projects node is a child of both the #opensource and #enterprise nodes, and the #badges node is a child of the #projects node. The #coverageBadge and #buildBadge nodes are children of the #badges node.

Database Reference

The database reference is an object created at runtime that contains the path details of every node of your database represented by the schema, which can be accessed through dot notation.

To generate a database reference, use the getPaths() function and pass in your schema string as an argument.

import { getPaths } from '@enio.ai/path-schema'

const dbRefs = getPaths(yourSchemaString)

Using the previous example, you can simply pass a template string directly.

import { getPaths } from '@enio.ai/path-schema'

const dbRefs = getPaths(`
  @root » #opensource #enterprise
  #opensource » #projects
  #enterprise » #projects
  #projects » #badges
  #badges » #coverageBadge #buildBadge
  #coverageBadge
  #buildBadge
`)

TypeScript Interface

Because the database reference is instanced at runtime, to get the benefit of IntelliSense to access properties in dot notation when you are using TypeScript, the getPaths() accepts an interface or type.

Here is an example;

import type { Reference } from '@enio.ai/path-schema'
import { getPaths } from '@enio.ai/path-schema'

type RootPaths = 'opensource' | 'enterprise'
type ProjectCategoryPaths = 'projects'
type ProjectPaths = 'badges'
type BadgePaths = 'coverageBadge' | 'buildBadge'

type Badges = Reference & {
  [key in BadgePaths]: Reference
}

type Project = Reference & {
  [key in ProjectPaths]: Badges
}

type ProjectCategories = Reference & {
  [key in ProjectCategoryPaths]: Project
}

type DB = Reference & {
  [key in RootPaths]: ProjectCategories
}

const dbRefs = getPaths<DB>(`
  @root » #opensource #enterprise
  #opensource » #projects
  #enterprise » #projects
  #projects » #badges
  #badges » #coverageBadge #buildBadge
  #coverageBadge
  #buildBadge
`)

Help with Advanced Database Schemas

Database schemas vary in complexity, and creating an interface could become less straightforward. You can use getDefinition().

getDefinition() takes in your schema string as an argument. The function will return a string that represents the TypeScript definitions for your database schema.

import { getDefinition } from '@enio.ai/path-schema'

console.log(
  getDefinition(`
  @root » #opensource #enterprise
  #opensource » #projects
  #enterprise » #projects
  #projects » #badges
  #badges » #coverageBadge #buildBadge
  #coverageBadge
  #buildBadge
`)
)

And that's it! You should now have a good understanding of how to model your own database schema using the getDefinition and getPaths functions. If you have any questions or need further clarification, feel free to ask.

@enio.ai/path-schema v0.2.0