Loopar Core Class - Loopar Framework

Overview

The Loopar class is the core of the Loopar Framework. It extends the Document class and provides essential functionality for application management, database operations, authentication, server initialization, and multi-tenancy support.

Installation

The Loopar instance is exported as a singleton and can be imported directly:

import { loopar } from 'loopar';

Constructor

const loopar = new Loopar();

The constructor initializes:

Date utilities (dateUtils)
Server instance
Database ORM connection
Unique tenant ID

Initialization

init(options)

Initializes the Loopar instance with tenant-specific configuration.

options

object

required

Configuration object for initialization

options.tenantId

string

required

Unique identifier for the tenant

options.appsBasePath

string

Base path for applications

await loopar.init({
  tenantId: 'my-tenant',
  appsBasePath: '/apps'
});

initialize()

Internal method that:

Builds the global environment
Loads configuration
Initializes the database
Builds the application
Builds icons
Initializes Tailwind CSS

await loopar.initialize();

Properties

Core Properties

pathRoot

string

Root path of the application (defaults to process.cwd())

tenantId

string

Current tenant identifier

tenantPath

string

File system path to tenant-specific data

pathCore

string

Path to Loopar core package

appsBasePath

string

Base path for installed applications

SequelizeORM

Database ORM instance

server

Server

HTTP server instance

auth

Auth

Authentication manager

utils

object

Collection of utility functions from Helpers

dateUtils

object

Date manipulation utilities

markdownRenderer

function

Markdown rendering function

Getters

authTokenName

string

Returns the authentication token name (format: loopar-{hash(tenantId)})

jwtSecret

string

Returns the JWT secret for token signing (SHA1 hash of tenant ID)

Cookie management instance from request context

session

SessionManager

Session management instance from request context

currentUser

object

Decoded JWT token data for the currently authenticated user

installedApps

object

Object containing all installed applications configuration

installing

boolean

Returns true if an app installation is in progress

Document Management

getDocument(document, name, data, options)

Retrieves a document instance by document type and name.

document

string

required

Document type name (e.g., ‘User’, ‘Entity’)

name

string

required

Document identifier/name

data

object

Optional data to merge with document

options.ifNotFound

string

default:"throw"

Behavior when document not found: ‘throw’ or ‘null’

options.parse

boolean

default:"false"

Whether to parse markdown fields

const user = await loopar.getDocument('User', 'john@example.com');
console.log(user.name, user.email);

newDocument(document, data)

Creates a new document instance (not yet saved to database).

document

string

required

Document type name

data

object

Initial document data

const newUser = await loopar.newDocument('User', {
  name: 'jane@example.com',
  email: 'jane@example.com',
  first_name: 'Jane'
});
await newUser.save();

deleteDocument(document, name, options)

Deletes a document from the database.

document

string

required

Document type name

name

string

required

Document identifier

options.sofDelete

boolean

default:"true"

Soft delete (mark as deleted) vs hard delete

options.force

boolean

default:"false"

Force delete even if document has connections

options.updateHistory

boolean

default:"true"

Create history entry for deletion

await loopar.deleteDocument('User', 'old-user@example.com', {
  sofDelete: true,
  force: false
});

getList(document, options)

Retrieves a paginated list of documents.

document

string

required

Document type name

options.fields

array

Fields to retrieve (defaults to list view fields)

options.filters

object

Filter conditions

options.q

object

Search query object

options.rowsOnly

boolean

default:"false"

Return only rows without metadata

const userList = await loopar.getList('User', {
  fields: ['name', 'email', 'first_name'],
  filters: { disabled: 0 },
  q: { name: 'john' }
});

console.log(userList.rows);
console.log(userList.pagination);

User & Authentication

getUser(userId)

Retrieves user data for authentication.

userId

string

User name or email

const user = await loopar.getUser('admin@example.com');

disabledUser(userId)

Checks if a user is disabled.

userId

string

required

User name or email

const isDisabled = await loopar.disabledUser('user@example.com');

App Management

setApp(app)

Registers or updates an installed application.

app

object

required

Application configuration object

await loopar.setApp({
  'my-app': {
    name: 'my-app',
    version: '1.0.0',
    installed: true
  }
});

unsetApp(appName)

Unregisters an installed application.

appName

string

required

Application name to remove

await loopar.unsetApp('my-app');

Database Configuration

getDbConfig()

Retrieves the current database configuration.

const dbConfig = loopar.getDbConfig();
console.log(dbConfig.host, dbConfig.database);

setDbConfig(config)

Updates the database configuration.

config

object

required

Database configuration object

await loopar.setDbConfig({
  host: 'localhost',
  port: 3306,
  database: 'my_db',
  username: 'root',
  password: 'secret'
});

Settings

systemsSettings()

Retrieves system settings document.

const settings = await loopar.systemsSettings();

getSettings()

Retrieves cached system settings.

const settings = await loopar.getSettings();

Git Operations

git(appName)

Returns a SimpleGit instance for app repository operations.

appName

string

Application name (optional)

const git = loopar.git('my-app');
await git.pull();
await git.add('.');
await git.commit('Update app');

gitRepositoryIsValid(repository)

Validates git repository URL format.

repository

string

required

Git repository URL

const isValid = loopar.gitRepositoryIsValid('https://github.com/user/repo.git');

validateGitRepository(appName, repository)

Validates and throws error if repository is invalid.

loopar.validateGitRepository('my-app', 'https://github.com/user/repo.git');

Utility Methods

hash(value)

Generates SHA1 hash of a value.

value

string

required

Value to hash

const hashed = loopar.hash('mypassword');

throw(error, redirect)

Throws a formatted error with optional redirect.

error

string|object

required

Error message or object with code and message

redirect

string

Optional redirect URL

loopar.throw('Invalid input');
// or
loopar.throw({ code: 404, message: 'Not found' }, '/login');

Example Usage

import { loopar } from 'loopar';

// Initialize with tenant
await loopar.init({
  tenantId: 'my-company',
  appsBasePath: '/apps'
});

// Create a new document
const user = await loopar.newDocument('User', {
  name: 'john@example.com',
  email: 'john@example.com',
  first_name: 'John',
  last_name: 'Doe'
});

await user.save();

// Retrieve and update
const existingUser = await loopar.getDocument('User', 'john@example.com');
existingUser.first_name = 'Johnny';
await existingUser.save();

// List users
const users = await loopar.getList('User', {
  filters: { disabled: 0 },
  fields: ['name', 'email', 'first_name']
});

console.log(`Found ${users.pagination.totalRecords} users`);

Additional Exports

SystemController

Extended controller for system-level operations. Inherits from BaseController with additional methods for system management tasks.

import { SystemController } from 'loopar';

export default class MySystemController extends SystemController {
  // System-level operations
}

Defined at packages/loopar/apps/core/modules/system/controllers/system/system-controller.js.

CoreInstaller

Internal class used for the framework installation wizard. Handles initial setup, database configuration, and site creation during first-time installation.

import { CoreInstaller } from 'loopar';

This is primarily used internally by Loopar and not typically extended by applications.

BaseDocument - Document class methods
BaseController - Controller class for routing
File Manager - File operations

Core Classes

Controllers

Utilities

​Overview

​Installation

​Constructor

​Initialization

​init(options)

​initialize()

​Properties

​Core Properties

​Getters

​Document Management

​getDocument(document, name, data, options)

​newDocument(document, data)

​deleteDocument(document, name, options)

​getList(document, options)

​User & Authentication

​getUser(userId)

​disabledUser(userId)

​App Management

​setApp(app)

​unsetApp(appName)

​Database Configuration

​getDbConfig()

​setDbConfig(config)

​Settings

​systemsSettings()

​getSettings()

​Git Operations

​git(appName)

​gitRepositoryIsValid(repository)

​validateGitRepository(appName, repository)

​Utility Methods

​hash(value)

​throw(error, redirect)

​Example Usage

​Additional Exports

​SystemController

​CoreInstaller

​Related

Build docs developers (and LLMs) love

Overview

Installation

Constructor

Initialization

init(options)

initialize()

Properties

Core Properties

Getters

Document Management

getDocument(document, name, data, options)

newDocument(document, data)

deleteDocument(document, name, options)

getList(document, options)

User & Authentication

getUser(userId)

disabledUser(userId)

App Management

setApp(app)

unsetApp(appName)

Database Configuration

getDbConfig()

setDbConfig(config)

Settings

systemsSettings()

getSettings()

Git Operations

git(appName)

gitRepositoryIsValid(repository)

validateGitRepository(appName, repository)

Utility Methods

hash(value)

throw(error, redirect)

Example Usage

Additional Exports

SystemController

CoreInstaller

Related