@kitledger/core 0.0.8 → 0.0.9

package/dist/accounts.d.ts

@@ -3,6 +3,7 @@ import * as v from "valibot";
 import { InferOutput } from "valibot";
 import { KitledgerDb } from "./db.js";
 import { FilterOperationParameters, GetOperationResult } from "./db.js";
+import { Ledger } from "./ledgers.js";
 import { accounts } from "./schema.js";
 import { ValidationFailure, ValidationSuccess } from "./validation.js";
 export declare enum BalanceType {
@@ -29,7 +30,7 @@ export type AccountCreateData = InferOutput<typeof AccountCreateSchema>;
  * @param params
  * @returns
  */
-export declare function filterAccounts(db: KitledgerDb, params: FilterOperationParameters): Promise<GetOperationResult<Account>>;
+export declare function filterAccounts(db: KitledgerDb, ledgers: Ledger[], params: FilterOperationParameters): Promise<GetOperationResult<Account>>;
 /**
  * Finds the parent account by ID or ref_id or alt_id.
  * Returns the ID of the parent account if found, otherwise returns null.
@@ -40,5 +41,5 @@ export declare function findParentAccount(db: KitledgerDb, parentId: string, led
  * @param ledgerId
  * @returns
  */
-export declare function findLedgerId(db: KitledgerDb, ledgerId: string): Promise<string | null>;
-export declare function createAccount(db: KitledgerDb, data: AccountCreateData): Promise<ValidationSuccess<Account> | ValidationFailure<AccountCreateData>>;
+export declare function findLedgerId(ledgers: Ledger[], ledgerId: string): Promise<string | null>;
+export declare function createAccount(db: KitledgerDb, ledgers: Ledger[], data: AccountCreateData): Promise<ValidationSuccess<Account> | ValidationFailure<AccountCreateData>>;

package/dist/accounts.js

@@ -2,7 +2,7 @@ import { and, eq, or, sql } from "drizzle-orm";
 import { v7 } from "uuid";
 import * as v from "valibot";
 import { ANY, defaultLimit, defaultOffset, maxLimit, parseBooleanFilterValue, } from "./db.js";
-import { accounts, ledgers } from "./schema.js";
+import { accounts } from "./schema.js";
 import { parseValibotIssues, } from "./validation.js";
 export var BalanceType;
 (function (BalanceType) {
@@ -26,7 +26,7 @@ export const AccountCreateSchema = v.object({
  * @param params
  * @returns
  */
-export async function filterAccounts(db, params) {
+export async function filterAccounts(db, ledgers, params) {
     const { limit = defaultLimit, offset = defaultOffset, ...filters } = params;
     const filterConditions = [];
     let ledgerId = null;
@@ -47,7 +47,7 @@ export async function filterAccounts(db, params) {
             filterConditions.push(sql `${accounts.name} ILIKE ${"%" + String(value) + "%"}`);
         }
         if (key === accounts.ledger_id.name && String(value).length > 0) {
-            ledgerId = await findLedgerId(db, String(value));
+            ledgerId = await findLedgerId(ledgers, String(value));
             if (ledgerId) {
                 filterConditions.push(eq(accounts.ledger_id, ledgerId));
             }
@@ -106,12 +106,9 @@ export async function findParentAccount(db, parentId, ledgerId) {
  * @param ledgerId
  * @returns
  */
-export async function findLedgerId(db, ledgerId) {
-    const ledger = await db.query.ledgers.findFirst({
-        where: and(or(eq(sql `${ledgers.id}::text`, ledgerId), eq(ledgers.ref_id, ledgerId), eq(ledgers.alt_id, ledgerId)), eq(ledgers.active, true)),
-        columns: { id: true },
-    });
-    return ledger ? ledger.id : null;
+export async function findLedgerId(ledgers, ledgerId) {
+    const ledger = ledgers.find((l) => l.refId === ledgerId);
+    return ledger ? ledger.refId : null;
 }
 // ACTIONS
 async function refIdAlreadyExists(db, refId) {
@@ -131,7 +128,7 @@ async function altIdAlreadyExists(db, altId) {
     });
     return results.length > 0;
 }
-async function validateAccountCreate(db, data) {
+async function validateAccountCreate(db, ledgers, data) {
     const result = v.safeParse(AccountCreateSchema, data);
     let success = result.success;
     if (!result.success) {
@@ -141,7 +138,7 @@ async function validateAccountCreate(db, data) {
     const [refIdError, altIdError, ledgerId] = await Promise.all([
         refIdAlreadyExists(db, result.output.ref_id),
         altIdAlreadyExists(db, result.output.alt_id ?? null),
-        findLedgerId(db, result.output.ledger_id),
+        findLedgerId(ledgers, result.output.ledger_id),
     ]);
     if (refIdError) {
         success = false;
@@ -187,8 +184,8 @@ async function validateAccountCreate(db, data) {
     }
     return { success, data: result.output, errors: errors };
 }
-export async function createAccount(db, data) {
-    const validation = await validateAccountCreate(db, data);
+export async function createAccount(db, ledgers, data) {
+    const validation = await validateAccountCreate(db, ledgers, data);
     if (!validation.success || !validation.data) {
         return {
             success: false,

package/dist/art.d.ts

@@ -1 +1,6 @@
+/**
+ * Returns an ASCII representation of the logo for display in the console.
+ *
+ * @returns A string representation of the ASCII logo.
+ */
 export declare function getAsciiLogo(): string;

package/dist/art.js

@@ -1,3 +1,8 @@
+/**
+ * Returns an ASCII representation of the logo for display in the console.
+ *
+ * @returns A string representation of the ASCII logo.
+ */
 export function getAsciiLogo() {
     return `.................................................................
 .................................................................

package/dist/db.d.ts

@@ -2,6 +2,13 @@ import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import * as v from "valibot";
 import * as schema from "./schema.js";
+/**
+ * Options for configuring the Kitledger database connection.
+ *
+ * @remarks
+ * Includes parameters for connection URL, SSL, connection pool size,
+ * migrations table and schema, and auto-migration setting.
+ */
 export type KitledgerDbOptions = {
     url: string;
     ssl?: boolean;
@@ -10,10 +17,26 @@ export type KitledgerDbOptions = {
     migrationsSchema?: string;
     autoMigrate?: boolean;
 };
+/**
+ * Database instance type for Kitledger, extending PostgresJsDatabase with the defined schema.
+ *
+ * @remarks
+ * Includes a reference to the underlying Postgres client.
+ */
 export type KitledgerDb = PostgresJsDatabase<typeof schema> & {
     $client: postgres.Sql<{}>;
 };
 export declare function runMigrations(db: KitledgerDb, migrationsTable: string, migrationsSchema: string): Promise<void>;
+/**
+ * Initializes the Kitledger database with the provided options.
+ *
+ * @remarks
+ * Sets up the database connection, applies migrations automatically if enabled,
+ * and returns the initialized database instance.
+ *
+ * @param options - Configuration options for the database connection.
+ * @returns A promise that resolves to the initialized Kitledger database instance.
+ */
 export declare function initializeDatabase(options: KitledgerDbOptions): Promise<KitledgerDb>;
 /**
  * Supported operation types for get operations.
@@ -43,13 +66,22 @@ export type GetOperationResult<T> = {
         message: string;
     }[];
 };
+/**
+ * Type definition for a single row in a query result.
+ */
 export type QueryResultRow = v.InferInput<typeof QueryResultRowSchema>;
+/**
+ * Schema definition for a single row in a query result.
+ */
 export declare const QueryResultRowSchema: v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BooleanSchema<undefined>, v.DateSchema<undefined>, v.NullSchema<undefined>, v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BooleanSchema<undefined>, v.DateSchema<undefined>, v.NullSchema<undefined>], undefined>, undefined>], undefined>, undefined>;
+/**
+ * Schema definition for an array of query result rows.
+ */
 export declare const QueryResultSchema: v.ArraySchema<v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BooleanSchema<undefined>, v.DateSchema<undefined>, v.NullSchema<undefined>, v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BooleanSchema<undefined>, v.DateSchema<undefined>, v.NullSchema<undefined>], undefined>, undefined>], undefined>, undefined>, undefined>;
 /**
  * Utility function to parse boolean filter values from strings or booleans to be used in queries and filters.
- * @param value
- * @returns
+ * @param value The value to parse, which can be a string or a boolean.
+ * @returns The parsed boolean value, or null if the input is not a valid boolean string.
  */
 export declare function parseBooleanFilterValue(value: string | boolean): boolean | null;
 /**

package/dist/db.js

@@ -7,6 +7,14 @@ import * as v from "valibot";
 import * as schema from "./schema.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+/*
+ * Runs database migrations using the specified migrations table and schema.
+ *
+ * @param db - The Kitledger database instance.
+ * @param migrationsTable - The name of the migrations table.
+ * @param migrationsSchema - The schema where the migrations table is located.
+ * @returns A promise that resolves when migrations are complete.
+ */
 export async function runMigrations(db, migrationsTable, migrationsSchema) {
     const migrationsPath = resolve(__dirname, "../dist/migrations");
     await migrate(db, {
@@ -15,6 +23,16 @@ export async function runMigrations(db, migrationsTable, migrationsSchema) {
         migrationsSchema: migrationsSchema,
     });
 }
+/**
+ * Initializes the Kitledger database with the provided options.
+ *
+ * @remarks
+ * Sets up the database connection, applies migrations automatically if enabled,
+ * and returns the initialized database instance.
+ *
+ * @param options - Configuration options for the database connection.
+ * @returns A promise that resolves to the initialized Kitledger database instance.
+ */
 export async function initializeDatabase(options) {
     const dbConfig = {
         url: options.url,
@@ -57,6 +75,9 @@ export var GetOperationType;
     GetOperationType["SEARCH"] = "search";
     GetOperationType["QUERY"] = "query";
 })(GetOperationType || (GetOperationType = {}));
+/**
+ * Schema definition for a single row in a query result.
+ */
 export const QueryResultRowSchema = v.record(v.string(), v.union([
     v.string(),
     v.number(),
@@ -65,11 +86,14 @@ export const QueryResultRowSchema = v.record(v.string(), v.union([
     v.null(),
     v.record(v.string(), v.union([v.string(), v.number(), v.boolean(), v.date(), v.null()])),
 ]));
+/**
+ * Schema definition for an array of query result rows.
+ */
 export const QueryResultSchema = v.array(QueryResultRowSchema);
 /**
  * Utility function to parse boolean filter values from strings or booleans to be used in queries and filters.
- * @param value
- * @returns
+ * @param value The value to parse, which can be a string or a boolean.
+ * @returns The parsed boolean value, or null if the input is not a valid boolean string.
  */
 export function parseBooleanFilterValue(value) {
     if (typeof value === "boolean") {

package/dist/entities.d.ts

@@ -1,11 +1,26 @@
 import type { Field } from "./fields.js";
+/**
+ * Enumeration for the status of an entity model.
+ */
 export declare enum EntityModelStatus {
     ACTIVE = 0,
     INACTIVE = 1
 }
+/**
+ * Infers the meta type of an entity based on its fields.
+ *
+ * @param TFields - An array of Field definitions.
+ * @returns A mapped type where each field's refId is the key and its value type is the value.
+ */
 export type InferEntityMetaType<TFields extends readonly Field[]> = {
     [K in TFields[number] as K["refId"]]: K["__valueType"];
 };
+/**
+ * Type definition for an entity in the system.
+ *
+ * @param TData - The type of the data contained within the entity.
+ * @returns An object representing the entity with its metadata and data.
+ */
 export type Entity<TData = Record<string, any>> = {
     id: string;
     modelRefId: string;
@@ -13,7 +28,18 @@ export type Entity<TData = Record<string, any>> = {
     updatedAt: Date;
     data: TData;
 };
+/**
+ * Type definition for a hook function that operates on an entity.
+ *
+ * @param TData - The type of the data contained within the entity.
+ * @returns A promise that resolves to the modified entity.
+ */
 export type EntityHook<TData> = (entity: Entity<TData>) => Promise<Entity<TData>>;
+/**
+ * Type definition for the hooks associated with an entity.
+ * @param TData - The type of the data contained within the entity.
+ * @returns An object containing arrays of hook functions for various entity lifecycle events.
+ */
 export type EntityHooks<TData = Record<string, any>> = {
     creating?: EntityHook<TData>[];
     updating?: EntityHook<TData>[];
@@ -22,6 +48,11 @@ export type EntityHooks<TData = Record<string, any>> = {
     updated?: EntityHook<TData>[];
     deleted?: EntityHook<TData>[];
 };
+/**
+ * Type definition for an entity model in the system.
+ *
+ * @returns An object representing the entity model with its metadata, fields, and hooks.
+ */
 export type EntityModel = {
     refId: string;
     altId?: string;
@@ -30,6 +61,12 @@ export type EntityModel = {
     fields?: Field[];
     hooks?: EntityHooks<any>;
 };
+/**
+ * Options for defining an entity model.
+ *
+ * @param TFields - An array of Field definitions.
+ * @returns An object containing the options for the entity model.
+ */
 export type EntityModelOptions<TFields extends readonly Field[]> = {
     refId: string;
     altId?: string;
@@ -38,6 +75,16 @@ export type EntityModelOptions<TFields extends readonly Field[]> = {
     fields?: TFields;
     hooks?: EntityHooks<InferEntityMetaType<TFields>>;
 };
+/**
+ * Defines an entity model with the provided options.
+ *
+ * @remarks
+ * This function helps in creating a strongly typed entity model by inferring
+ * the types of the fields provided.
+ *
+ * @param options The options for defining the entity model.
+ * @returns A strongly typed entity model.
+ */
 export declare function defineEntityModel<const TFields extends readonly Field[]>(options: EntityModelOptions<TFields>): EntityModel & {
     fields: TFields;
 };

package/dist/entities.js

@@ -1,8 +1,21 @@
+/**
+ * Enumeration for the status of an entity model.
+ */
 export var EntityModelStatus;
 (function (EntityModelStatus) {
     EntityModelStatus[EntityModelStatus["ACTIVE"] = 0] = "ACTIVE";
     EntityModelStatus[EntityModelStatus["INACTIVE"] = 1] = "INACTIVE";
 })(EntityModelStatus || (EntityModelStatus = {}));
+/**
+ * Defines an entity model with the provided options.
+ *
+ * @remarks
+ * This function helps in creating a strongly typed entity model by inferring
+ * the types of the fields provided.
+ *
+ * @param options The options for defining the entity model.
+ * @returns A strongly typed entity model.
+ */
 export function defineEntityModel(options) {
     return {
         ...options,

package/dist/factories.d.ts

@@ -1,6 +1,5 @@
 import { Account } from "./accounts.js";
 import { ApiToken, Permission, PermissionAssignment, Role, SystemPermission, User, UserRole } from "./auth.js";
-import { Ledger } from "./ledgers.js";
 /**
  * A generic factory function to create an array of items.
  * @param factory A function that creates a single item.
@@ -37,9 +36,6 @@ export declare class UserFactory extends BaseFactory<User> {
 export declare class UserRoleFactory extends BaseFactory<UserRole> {
     constructor();
 }
-export declare class LedgerFactory extends BaseFactory<Ledger> {
-    constructor();
-}
 export declare class AccountFactory extends BaseFactory<Account> {
     constructor();
 }

package/dist/factories.js

@@ -115,26 +115,11 @@ const makeUserRole = () => ({
     created_at: faker.date.past(),
     updated_at: faker.date.recent(),
 });
-export class LedgerFactory extends BaseFactory {
-    constructor() {
-        super(makeLedger);
-    }
-}
 export class AccountFactory extends BaseFactory {
     constructor() {
         super(makeAccount);
     }
 }
-const makeLedger = () => ({
-    id: v7(),
-    ref_id: v7(),
-    alt_id: v7(),
-    name: faker.company.name(),
-    description: faker.company.catchPhrase(),
-    active: true,
-    created_at: faker.date.past(),
-    updated_at: faker.date.recent(),
-});
 const makeAccount = () => ({
     id: v7(),
     ref_id: v7(),

package/dist/fields.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Enumeration of supported field types.
+ */
 export declare enum FieldType {
     TEXT = "text",
     NUMBER = "number",
@@ -7,18 +10,27 @@ export declare enum FieldType {
     SELECT = "select",
     RELATION = "relation"
 }
+/**
+ * Base interface for all field definitions.
+ */
 interface BaseField {
     readonly refId: string;
     name: string;
     description?: string;
     required: boolean;
 }
+/**
+ * Type definition for a text field.
+ */
 export interface TextField extends BaseField {
     type: FieldType.TEXT;
     readonly __valueType: string;
     maxLength?: number;
     format?: "email" | "plain" | "rich_text";
 }
+/**
+ * Type definition for a number field.
+ */
 export type NumberFormatting = {
     style: "integer";
 } | {
@@ -28,6 +40,9 @@ export type NumberFormatting = {
     style: "currency";
     currencyCode: string;
 };
+/**
+ * Type definition for a number field.
+ */
 export interface NumberField extends BaseField {
     type: FieldType.NUMBER;
     readonly __valueType: number;
@@ -35,23 +50,38 @@ export interface NumberField extends BaseField {
     max?: number;
     formatting: NumberFormatting;
 }
+/**
+ * Type definition for a date field.
+ */
 export interface DateField extends BaseField {
     type: FieldType.DATE;
     readonly __valueType: Date;
     includeTime: boolean;
     formatStr: string;
 }
+/**
+ * Type definition for a boolean field.
+ */
 export interface BooleanField extends BaseField {
     type: FieldType.BOOLEAN;
     readonly __valueType: boolean;
     defaultValue?: boolean;
 }
+/**
+ * Type definition for a URL field.
+ */
 export interface URLField extends BaseField {
     type: FieldType.URL;
     readonly __valueType: string;
     defaultValue?: string;
 }
+/**
+ * TEMPORARY: Type definition for query configuration in relation fields.
+ */
 export type QueryConfig = {};
+/**
+ * Type definition for a select field.
+ */
 export interface SelectField extends BaseField {
     type: FieldType.SELECT;
     readonly __valueType: string | number | (string | number)[];
@@ -63,6 +93,9 @@ export interface SelectField extends BaseField {
     }>;
     defaultValue?: string | number | Array<string | number>;
 }
+/**
+ * Type definition for a relation field.
+ */
 export interface RelationField extends BaseField {
     type: FieldType.RELATION;
     readonly __valueType: any;
@@ -71,28 +104,61 @@ export interface RelationField extends BaseField {
     displayFieldId: string;
     query: QueryConfig;
 }
+/**
+ * Union type for all field definitions.
+ */
 export type Field = TextField | NumberField | DateField | BooleanField | URLField | SelectField | RelationField;
+/**
+ * Options for defining a text field.
+ */
 export type TextFieldOptions = Omit<TextField, "type" | "__valueType" | "refId" | "required"> & {
     required?: boolean;
 };
+/**
+ * Options for defining other field types.
+ */
 export type NumberFieldOptions = Omit<NumberField, "type" | "__valueType" | "refId" | "required"> & {
     required?: boolean;
 };
+/**
+ * Options for defining other field types.
+ */
 export type DateFieldOptions = Omit<DateField, "type" | "__valueType" | "refId" | "required"> & {
     required?: boolean;
 };
+/**
+ * Options for defining other field types.
+ */
 export type BooleanFieldOptions = Omit<BooleanField, "type" | "__valueType" | "refId" | "required"> & {
     required?: boolean;
 };
+/**
+ * Options for defining other field types.
+ */
 export type URLFieldOptions = Omit<URLField, "type" | "__valueType" | "refId" | "required"> & {
     required?: boolean;
 };
+/**
+ * Options for defining other field types.
+ */
 export type SelectFieldOptions = Omit<SelectField, "type" | "__valueType" | "refId" | "required"> & {
     required?: boolean;
 };
+/**
+ * Options for defining other field types.
+ */
 export type RelationFieldOptions = Omit<RelationField, "type" | "__valueType" | "refId" | "required"> & {
     required?: boolean;
 };
+/**
+ * Factory functions to define fields of various types.
+ *
+ * @remarks
+ * These functions help in creating strongly typed field definitions by inferring
+ *
+ * @param options - The options for defining the field.
+ * @returns The defined field with its type.
+ */
 export declare function defineTextField<const T extends string, const R extends boolean = false>(options: TextFieldOptions & {
     refId: T;
     required?: R;
@@ -100,6 +166,15 @@ export declare function defineTextField<const T extends string, const R extends
     refId: T;
     required: R;
 };
+/**
+ * Factory function to define a number field.
+ *
+ * @remarks
+ * These functions help in creating strongly typed field definitions by inferring
+ *
+ * @param options - The options for defining the field.
+ * @returns The defined field with its type.
+ */
 export declare function defineNumberField<const T extends string, const R extends boolean = false>(options: NumberFieldOptions & {
     refId: T;
     required?: R;
@@ -107,6 +182,15 @@ export declare function defineNumberField<const T extends string, const R extend
     refId: T;
     required: R;
 };
+/**
+ * Factory function to define a date field.
+ *
+ * @remarks
+ * These functions help in creating strongly typed field definitions by inferring
+ *
+ * @param options - The options for defining the field.
+ * @returns The defined field with its type.
+ */
 export declare function defineDateField<const T extends string, const R extends boolean = false>(options: DateFieldOptions & {
     refId: T;
     required?: R;
@@ -114,6 +198,15 @@ export declare function defineDateField<const T extends string, const R extends
     refId: T;
     required: R;
 };
+/**
+ * Factory function to define a boolean field.
+ *
+ * @remarks
+ * These functions help in creating strongly typed field definitions by inferring
+ *
+ * @param options - The options for defining the field.
+ * @returns The defined field with its type.
+ */
 export declare function defineBooleanField<const T extends string, const R extends boolean = false>(options: BooleanFieldOptions & {
     refId: T;
     required?: R;
@@ -121,6 +214,11 @@ export declare function defineBooleanField<const T extends string, const R exten
     refId: T;
     required: R;
 };
+/**
+ * Factory function to define a URL field.
+ * @param options - The options for defining the field.
+ * @returns The defined field with its type.
+ */
 export declare function defineURLField<const T extends string, const R extends boolean = false>(options: URLFieldOptions & {
     refId: T;
     required?: R;
@@ -128,6 +226,15 @@ export declare function defineURLField<const T extends string, const R extends b
     refId: T;
     required: R;
 };
+/**
+ * Factory function to define a select field.
+ *
+ * @remarks
+ * These functions help in creating strongly typed field definitions by inferring
+ *
+ * @param options - The options for defining the field.
+ * @returns The defined field with its type.
+ */
 export declare function defineSelectField<const T extends string, const R extends boolean = false>(options: SelectFieldOptions & {
     refId: T;
     required?: R;
@@ -135,6 +242,15 @@ export declare function defineSelectField<const T extends string, const R extend
     refId: T;
     required: R;
 };
+/**
+ * Factory function to define a relation field.
+ *
+ * @remarks
+ * These functions help in creating strongly typed field definitions by inferring
+ *
+ * @param options - The options for defining the field.
+ * @returns The defined field with its type.
+ */
 export declare function defineRelationField<const T extends string, const R extends boolean = false>(options: RelationFieldOptions & {
     refId: T;
     required?: R;