@elqnt/entity

Complete entity management for the Eloquent platform. Fully typed, zero any.

Installation

pnpm add @elqnt/entity

Quick Start

import { useEntityDefinitions, useEntityRecords } from "@elqnt/entity/hooks";

// Definitions
const { listDefinitions, createDefinition } = useEntityDefinitions({
  baseUrl: apiGatewayUrl,
  orgId,
});

// Records for a specific entity
const { queryRecords, createRecord, aggregateRecords } = useEntityRecords({
  baseUrl: apiGatewayUrl,
  orgId,
  entityName: "ticket",
});

const result = await queryRecords({ filters: { status: "open" }, page: 1, pageSize: 20 });
// result: PaginatedResult<EntityRecord>

Hooks

useEntityDefinitions(options)

const {
  loading, error,
  listDefinitions,    // (params?) => EntityDefinition[]
  getDefinition,      // (entityName) => EntityDefinition | null
  createDefinition,   // (definition) => string (id)
  updateDefinition,   // (entityName, definition) => boolean
  deleteDefinition,   // (entityName, params?) => boolean
  listViews,          // (entityName) => EntityView[]
  createView,         // (entityName, view) => string (id)
  updateView,         // (entityName, viewId, view) => boolean
  deleteView,         // (entityName, viewId) => boolean
} = useEntityDefinitions({ baseUrl, orgId });

useEntityRecords(options)

const {
  loading, error,
  // Records
  queryRecords,       // (params?) => PaginatedResult<EntityRecord>
  getRecord,          // (recordId) => EntityRecord | null
  createRecord,       // (record) => EntityRecord | null
  updateRecord,       // (recordId, record) => boolean
  deleteRecord,       // (recordId) => boolean
  countRecords,       // (filters?) => number
  // Aggregations
  aggregateRecords,   // (request) => AggregateResponse
  // Bulk
  bulkCreate,         // (records) => BulkResult
  bulkUpdate,         // (records) => BulkResult
  bulkDelete,         // (recordIds) => BulkResult
  // Relationships
  createRelationship, // (recordId, rel) => EntityRelationship | null
  listRelationships,  // (recordId, params?) => EntityRelationship[]
  deleteRelationship, // (recordId, relId) => boolean
} = useEntityRecords({ baseUrl, orgId, entityName: "ticket" });

Query Records

Basic filter

const result = await queryRecords({ filters: { status: "open" } });
// PaginatedResult { records, totalCount, currentPage, pageSize, totalPages, hasNextPage, hasPreviousPage }

Operator form

const result = await queryRecords({
  filters: {
    priority: { "$in": ["high", "urgent"] },
    created_at: { "$gte": "2024-01-01T00:00:00Z" },
  },
  sortBy: "created_at",
  sortOrder: "desc",
});

Full-text search

const result = await queryRecords({
  filters: { "$search": "login page error" },
});

Vector similarity search

const result = await queryRecords({
  filters: { "$similar": "customer unable to access dashboard" },
});

Combined filters

const result = await queryRecords({
  filters: {
    "$search": "payment",
    status: "open",
    priority: { "$in": ["high", "urgent"] },
  },
});

Field selection

// Include only specific fields
const result = await queryRecords({
  include: ["title", "status", "priority"],
});

// Exclude fields
const result = await queryRecords({
  exclude: ["internal_notes"],
});

Lookups

const result = await queryRecords({
  includeLookups: [{
    entityName: "user",
    fieldName: "assignee_id",
    fields: ["name", "email"],
  }],
});

Pagination

const page1 = await queryRecords({ page: 1, pageSize: 20 });
if (page1.hasNextPage) {
  const page2 = await queryRecords({ page: 2, pageSize: 20 });
}

Aggregations

const stats = await aggregateRecords({
  filters: { status: "published" },
  groupBy: ["category"],
  aggregates: [
    { field: "*", function: "count", alias: "total" },
    { field: "price", function: "sum", alias: "revenue" },
    { field: "rating", function: "avg", alias: "avg_rating" },
  ],
  sortBy: "total",
  sortOrder: -1,
});
// stats.groups: [{ key: { category: "Books" }, values: { total: 42, revenue: 1200 }, count: 42 }]
// stats.totals: { total: 100, revenue: 5000, avg_rating: 4.2 }

Supported functions: count, sum, avg, min, max, distinct_count.

Relationships

// Create
const rel = await createRelationship("session-id", {
  toEntityName: "training_program",
  toRecordId: "program-id",
  relationshipType: "session_of",
  fields: { role: "primary" },
});

// List
const rels = await listRelationships("session-id", {
  direction: "outgoing",
  relationshipType: "session_of",
});

// Delete
await deleteRelationship("session-id", rel.id);

Bulk Operations

const created = await bulkCreate([
  { fields: { title: "Issue 1", status: "open" } },
  { fields: { title: "Issue 2", status: "open" } },
]);
// created: { message: "Records created successfully", count: 2 }

const updated = await bulkUpdate([
  { id: "uuid-1", fields: { status: "closed" } },
  { id: "uuid-2", fields: { status: "closed" } },
]);

const deleted = await bulkDelete(["uuid-1", "uuid-2"]);

Types

All backend types are generated from Go via tygo generate. Never edit models/entity.ts manually.

import type { EntityRecord, EntityDefinition, EntityView } from "@elqnt/entity/models";
import type { AggregateRequest, AggregateResponse } from "@elqnt/entity/models";
import type { EntityRelationship, CreateRelationshipRequest } from "@elqnt/entity/models";
import type { PaginatedResult, BulkResult } from "@elqnt/entity/hooks";

API Functions

For non-React usage or server-side calls:

import { queryEntityRecordsApi, aggregateEntityRecordsApi } from "@elqnt/entity/api";

Migration from v2

v3 removes the legacy useEntities hook. Replace with two hooks:

// v2
const { queryRecords, listDefinitions } = useEntities(options);
await queryRecords("ticket", { filters: { status: "open" } });
await listDefinitions();

// v3
const { listDefinitions } = useEntityDefinitions(options);
const { queryRecords } = useEntityRecords({ ...options, entityName: "ticket" });
await queryRecords({ filters: { status: "open" } });
await listDefinitions();

Key changes:

• queryRecords no longer takes entityName as first arg — it's in the hook options
• queryRecords returns PaginatedResult<EntityRecord> (with totalPages, hasNextPage, hasPreviousPage)
• updateRecord / deleteRecord return boolean (not the record)
• Bulk operations return BulkResult ({ message, count })
• createDefinition returns the id string (not the full definition)