Uranio

Uranio command line interface.

Table of Contents

• About
• Installation
• Usage
• Commands
• Getting started
• How to start developing

---

About

uranio is the only package you need in order to work with Uranio.

Uranio is a Typescript framework for developing CRUD API. It generates the CRUD [Create, Read, Update, Delete] methods for querying a database.

A database relation in Uranio is called Atom.

Uranio two main features are:

1. Uranio makes possible to define new Atoms and to use them in the current project, so that each projects have its own Atoms.

2. Uranio makes also possible to have code completition and intelisense with the new defined Atoms.

Uranio can be installed as one of the following repo:

• uranio-core (Serverside)
• uranio-api (Serverside, Webservice)
• uranio-trx (Serverside, Webservice, Clientside)
• uranio-adm (Serverside, Webservice, Clientside, Admin panel)

Each repo includes the previous one.

Core

uranio-core generates classes needed to interact with the database.

Uranio can interact with the following databases: MongoDB

More Database will be implemented in the future.

Api

uranio-api runs a web service that expose a CRUD API.

The web service use Express.js internally.

Uranio API can also be used inside a Lambda Function. It has a method that creates a service to use inside Netlify Functions.

uranio.api.lambda.create();

TRX

uranio-trx creates Hooks that can be used to query the API from a client.

See Hooks

ADM

uranio-adm creates a full Administration Panel that interact with the API.

---

Installation

Uranio requires Node.js, version 14 or above. To install uranio, run the following command from any directory in your terminal:

Global installation (recommended)

npm install --global uranio

or if you are using yarn

yarn global add uranio

or if you are using pnpm

pnpm global add uranio

Local installation

Warning

To install locally the command must be the following otherwise there will be conflicts with package names.

npm install uranio-cli@npm:uranio

or if you are using yarn

yarn add uranio-cli@npm:uranio

or if you are using pnpm

pnpm add uranio-cli@npm:uranio

---

Usage

Installing the CLI globally provides access to the uranio command.

uranio [command]

Run help for detailed information about CLI commands

uranio help

Shortcut

urn [command]

---

Commands

init

uranio init

This command initialize the repository. It will download and install all dependencies and copy all the files needed in order to start developing.

Flags

• -s --root (string) - Set project root. If empty Uranio will auto detect the closest repo.
• -r --repo (string) - Set Uranio repo [core, api, trx, adm].
• -f --force (boolean) - Run without prompts.
• -m --pacman (string) - Set package manager [npm, yarn, pnpm].

start

uranio start

This command starts the server and the admin panel for production.

Flags

• -p --prod (boolean) - Run in production mode.

dev

uranio dev

This command starts a local development server.

Flags

• -p --prod (boolean) - Run in production mode.

deinit

uranio deinit

This command deletes everything uranio created and return the repo in its initial state.

info

uranio info

This command prints the main uranio information for the current repo.

help

uranio help

This command prints the list of all commands, parameters and options.

version

uranio version

#or

uranio

This command prints uranio version.

---

Output options

• -v --verbose (boolean) - log in verbose mode [same as --log_level=debug].
• -u --trace (boolean) - log in trace mode [same as --log_level=trace].
• -n --no_colors (boolean) - log with no colors.
• -w --fullwidth (boolean) - log in full width.
• -t --time (boolean) - log with timestamp.
• -g --filelog (boolean) - save log on file.
• -i --spin (boolean) - log with spinner.
• -e --prefix (string) - set a log prefix.
• -l --log_level (string) - set log level [none, error, warn, info, debug, trace]
• -x --prefix_loglevel (boolean) - prefix log type.

---

Getting started

Change directory to your node repo:

cd /path/to/my/repo

If not already, run:

npm init

or if you are using yarn

yarn init

or if you are using pnpm

pnpm init

Then initialize Uranio with:

uranio init

The command will prompt with questions regarding the repository you want to initialize.

• Choose the package manager [yarn, npm, pnpm]

• Choose the uranio module you want to use: [core, api, trx, adm]

This might take a while, depending on your internet connection.

After it is done, your repo is ready for development.

In order to start developing you will need to create and run a development server. Run:

uranio dev

Here you will see all the logs, also it will print the IP of the Admin panel in the case of the adm repo.

Now you can start developing.

---

How to start developing

The first things that need to be defined in Uranio are Atoms.

Atoms are the objects stored in the database.

For example if we want to define an Atom with the name product, we need to create the directory src/atoms/product and the file src/atoms/prodcut/index.ts.

The name product will be picked from the name of the directory just created.

The src/atoms/product/index.ts must export a default object with the Atom definition, like so:

import uranio from 'uranio';

export default uranio.register.atom({
	properties: {
		title: {
			type: uranio.types.PropertyType.TEXT,
			label: 'Title'
		},
		price: {
			type: uranio.types.PropertyType.FLOAT,
			label: 'Price'
		},
		// ...
	},
	// ...
});

Uranio already creates the following required Atoms:

Core

• superuser
• user
• group
• media

Api

• request
• error

Admin

• setting

Atom register

The parameter of the function uranio.register.atom used in src/atoms/product/index.ts is of type:

uranio.types.Book.Definition.

properties: Book.Definition.Properties
plural?: string
authenticate?: boolean
connection?: ConnectionName
security?: Book.Definition.Security
dock?: Book.Definition.Dock

A full Atom definition would be like this:

import uranio from 'uranio';

export default uranio.register.atom({
	plural: 'customers',
	authenticate: true,
	security: {
		type: uranio.types.BookSecurityType.UNIFORM,
		_r: uranio.types.BookPermissionType.NOBODY
	},
	connection: 'main',
	properties: {
		full_name: {
			type: uranio.types.PropertyType.TEXT,
			label: 'Full name'
		},
		email: {
			type: uranio.tyoes.PropertyType.EMAIL,
			label: 'Email'
		},
		password: {
			type: uranio.tyoes.PropertyType.ENCRYPTED,
			label: 'Password',
			hidden: true
		},
		groups: {
			type: uranio.tyoes.PropertyType.ATOM,
			label: 'Group',
			atom: 'group',
			optional: true
		},
	},
	dock: {
		url: '/products'
	}
});

Plural

plural defines the plural word to define the Atom.

e.g.: For the Atom product will be products.

Authenticate

authenticate defines if the Atom is an AuthAtom.

See AuthAtom

AuthAtom are Atoms that can be authenticated, meaning they have methods that authenticate with email and password.

For example they can be used to define customers.

Uranio already provide 2 AuthAtoms: superuser and user.

Connection

connection define with which connection the Atom is stored.

connection can be one of the follwing: main (default), log, trash.

Uranio creates 3 database with 3 different connections.

• The main connection is where are stored all the main Atoms.
• The log connection is where are stored the Atoms that define logs.
• The trash connection is where Uranio put the deleted Atoms.

Uranio API already provide 2 Atoms that are used in the log connection. They are request and error. For each API request an Atom request is stored. For each Uranio error and Atom error is stored.

Security

security define the security of the Atom, meaning how the database can be queried.

Uranio creates an Access Control Layer (ACL) before querying the database. This will check if the request can read or write in the database.

Each Atom relation can have its own rules.

security can be of type:

• uranio.types.SecurityType.UNIFORM.
• uranio.types.SecurityType.GRANULAR.

Default is UNIFORM.

UNIFORM permission will check on a relation level, meaning that the rule is defined for the entire Atom relation.

GRANULAR permission will check on a record level, meaning that the rules can differ between the records. Each record has its own write and read rules.

Each relation / record has two attributes _r and _w, respectively for reading and writing permission. The value of these attributes is an Atom group ID Array.

_r will narrow from Everybody

_w will widen from Nobody

_r == nullish -> Everybody can read

_w == nullish -> Nobody can write

For example:

// src/atoms/product/index.ts

import uranio from 'uranio';

export default uranio.register.atom({
	// ...
	security: {
		type: uranio.types.BookSecurityType.UNIFORM,
		_r: uranio.types.BookPermissionType.NOBODY
	},
	// ...
});

The above definition means that Nobody can read or write on the entire Atom relation.

// src/atoms/product/index.ts

import uranio from 'uranio';

export default uranio.register.atom({
	// ...
	security: {
		type: uranio.types.BookSecurityType.UNIFORM,
		_w: uranio.types.BookPermissionType.PUBLIC
	},
	// ...
});

The above definition means that Everybody can read and write on the entire Atom relation without authenitcation.

// src/atoms/product/index.ts

import uranio from 'uranio';

export default uranio.register.atom({
	// ...
	security: {
		type: uranio.types.BookSecurityType.UNIFORM,
		_w: ['61d81a12f3e4ea6edbdcdd1e', '61d81a12f3e4ea6edbwcddff']
	},
	// ...
});

The above definition means that Everybody can read but only authenitcated AuthAtom that have groups with the following ids: ['61d81a12f3e4ea6edbdcdd1e', '61d81a12f3e4ea6edbwcddff'] can write.

// src/atoms/product/index.ts

import uranio from 'uranio';

export default uranio.register.atom({
	// ...
	security: {
		type: uranio.types.BookSecurityType.GRANULAR,
	},
	// ...
});

When the security type is GRANULAR, the ACL will check if the singles Atoms have the right permission to be read or written.

Dock

dock have a url property that must start with /.

For example:

// src/atoms/product/index.ts

import uranio from 'uranio';

export default uranio.register.atom({
	// ...
	dock: {
		url: '/products'
	},
	// ...
});

will create a route in the webserice https://[WEBSERVICEURL]/uranio/api/products where the Atom relation product can be queried.

[WEBSERVICEURL] can be defined in uranio.toml.

/uranio/api prefix can be defined in uranio.toml.

See uranio.toml definition

dock has also the properties auth_url that need to be defined when authenticate is equal to true.

auth_url define the route url where the AuthAtom can authenticate.

For example:

// src/atoms/customer/index.ts

import uranio from 'uranio';

export default uranio.register.atom({
	// ...
	dock: {
		url: '/customers',
		auth_url: '/auth-customer'
	},
	// ...
});

will create a route in the webservice https://[WEBSERVICEURL]/uranio/api/auth-customer

tha will accept as body in JSON format:

{
	email: 'uranio@email.com',
	password: 'MyPassword1234'
}

and will return an AuthResponse object with a token and a http-only cookie if authenitcated.

Properties

Type Book.Definition.Properties is a list of all the relation key.

Each key is of type Book.Definition.Property:

//type Book.Definition.Property

Property.ID |
Property.Text |
Property.LongText |
Property.Email |
Property.Integer |
Property.Float |
Property.Binary |
Property.Encrypted |
Property.Day |
Property.Time |
Property.SetString |
Property.SetNumber |
Property.EnumString |
Property.EnumNumber |
Property.Atom |
Property.AtomArray;

Each property type has the following common properties:

type: BookPropertyType
label: string
optional?: boolean
hidden?: boolean
unique?: boolean
default?: any
on_error?: (old_value: any) => any

BookPropertyType can be one of the following

// BookPropertyType

ID = 'ID',
TEXT = 'TEXT',
LONG_TEXT = 'LONG_TEXT',
EMAIL = 'EMAIL',
INTEGER = 'INTEGER',
FLOAT = 'FLOAT',
BINARY = 'BINARY',
ENCRYPTED = 'ENCRYPTED',
DAY = 'DAY',
TIME = 'TIME',
ENUM_STRING = 'ENUM_STRING',
ENUM_NUMBER = 'ENUM_NUMBER',
SET_STRING = 'SET_STRING',
SET_NUMBER = 'SET_NUMBER',
ATOM = 'ATOM',
ATOM_ARRAY = 'ATOM_ARRAY'