@kitledger/core 0.0.7 → 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

@@ -0,0 +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

@@ -0,0 +1,42 @@
+/**
+ * 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

@@ -2,19 +2,37 @@ import { drizzle } from "drizzle-orm/postgres-js";
 import { migrate } from "drizzle-orm/postgres-js/migrator";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import postgres from "postgres";
 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");
-    console.log("***Using migrations path:", migrationsPath);
     await migrate(db, {
         migrationsFolder: migrationsPath,
         migrationsTable: migrationsTable,
         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,
@@ -22,8 +40,20 @@ export async function initializeDatabase(options) {
         max: options.max ? options.max : 10,
         autoMigrate: options.autoMigrate ?? true,
     };
+    const queryClient = postgres(dbConfig.url, {
+        ssl: dbConfig.ssl,
+        max: dbConfig.max,
+        onnotice: (msg) => {
+            /**
+             * Ignore notices about skipping already applied migrations
+             */
+            if (!msg.message.includes("skipping")) {
+                console.log("Kitledger Postgres notice:", msg);
+            }
+        },
+    });
     const db = drizzle({
-        connection: dbConfig,
+        client: queryClient,
         schema: schema,
     });
     const migrationsTable = options.migrationsTable || "schema_history";
@@ -45,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(),
@@ -53,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,19 +1,45 @@
 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["ref_id"]]: K["__primitive_type"];
+    [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;
-    model_ref_id: string;
-    created_at: Date;
-    updated_at: Date;
+    modelRefId: string;
+    createdAt: Date;
+    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,20 +48,43 @@ 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 = {
-    ref_id: string;
-    alt_id?: string;
+    refId: string;
+    altId?: string;
     name: string;
     status: EntityModelStatus;
     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[]> = {
-    ref_id: string;
-    alt_id?: string;
+    refId: string;
+    altId?: string;
     name: string;
     status?: EntityModelStatus;
     fields?: TFields;
     hooks?: EntityHooks<InferEntityMetaType<TFields>>;
 };
-export declare function defineEntityModel<const TFields extends readonly Field[]>(options: EntityModelOptions<TFields>): EntityModel;
+/**
+ * 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,14 +1,26 @@
+/**
+ * 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) {
-    const entityModel = {
+    return {
         ...options,
         status: options.status ?? EntityModelStatus.ACTIVE,
         fields: options.fields,
         hooks: options.hooks,
     };
-    return entityModel;
 }

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(),