jopi-toolkit 3.1.32 → 3.1.37

package/src/jk_app/common.ts

@@ -291,12 +291,22 @@ export function getCompiledCodeDir(): string {
     return rootDir;
 }
 
+export function toSourceCodeDir(itemPath: string): string {
+    const compiledDir = getCompiledCodeDir();
+
+    if (itemPath.startsWith(compiledDir)) {
+        return getSourceCodeDir() + itemPath.substring(compiledDir.length);
+    }
+
+    return itemPath;
+}
+
 export function getCompiledFilePathFor(sourceFilePath: string, replaceExtension = true): string {
     const compiledCodeDir = getCompiledCodeDir();
     const sourceCodeDir = getSourceCodeDir();
 
     if (!sourceFilePath.startsWith(sourceCodeDir)) {
-        throw new Error("jopi-loader - The source file must be in the source code directory: " + sourceFilePath);
+        return sourceFilePath;
     }
 
     let filePath = sourceFilePath.substring(sourceCodeDir.length);
@@ -321,7 +331,7 @@ export function getSourcesCodePathFor(compiledFilePath: string): string {
     const sourceCodeDir = getSourceCodeDir();
 
     if (!compiledFilePath.startsWith(compiledCodeDir)) {
-        throw new Error("jopi-loader - The compiled file must be in the compiled code directory: " + compiledFilePath);
+        return compiledCodeDir;
     }
 
     let filePath =  jk_fs.join(sourceCodeDir, compiledFilePath.substring(compiledCodeDir.length));

package/src/jk_data/core.ts

@@ -0,0 +1,92 @@
+import {type Schema} from "jopi-toolkit/jk_schema";
+import type { JopiDataTable, JDataReadParams, JDataReadResult, JRowArrayFilter } from "./interfaces.ts";
+export * from "./interfaces.ts";
+
+//region Rows Arrays
+
+/**
+ * Filter the row content according to rules.
+ */
+export function simpleRowArrayFilter(rows: any[], params: JRowArrayFilter): JDataReadResult {
+    // > Apply filter.
+
+    if (params.filter) {
+        const f = params.filter;
+
+        rows = rows.filter(r => {
+            if (f.field) {
+                let v = r[f.field];
+                if (v===undefined) return false;
+                return String(v).includes(f.value);
+            } else {
+                for (let v of Object.values(r)) {
+                    if (v===undefined) continue;
+                    if (String(v).includes(f.value)) return true;
+                }
+
+                return false;
+            }
+        });
+    }
+
+    // > Apply sorting.
+
+    if (params.sorting && params.sorting.length) {
+        const sorting = params.sorting[0];
+        const sortField = sorting.id;
+        const sortDesc = sorting.desc;
+
+        rows = rows.sort((a, b) => {
+            let av = a[sortField];
+            let bv = b[sortField];
+
+            if (av === undefined) av = "";
+            if (bv === undefined) bv = "";
+
+            const avIsNumber = typeof av === "number";
+            const bvIsNumber = typeof bv === "number";
+
+            if (avIsNumber && bvIsNumber) {
+                if (sortDesc) {
+                    return bv - av;
+                } else {
+                    return av - bv;
+                }
+            } else {
+                const avStr = String(av);
+                const bvStr = String(bv);
+
+                if (sortDesc) {
+                    return bvStr.localeCompare(avStr);
+                } else {
+                    return avStr.localeCompare(bvStr);
+                }
+            }
+        });
+    }
+
+    const totalWithoutPagination = rows.length;
+    let offset = 0;
+
+    if (params.page) {
+        offset = params.page.pageIndex * params.page.pageSize;
+        rows = rows.slice(offset, offset + params.page.pageSize);
+    }
+
+    return {rows, total: totalWithoutPagination, offset};
+}
+
+//endregion
+
+//region JDataBinding
+
+export class JDataBinding_UseArray implements JopiDataTable {
+    public constructor(public readonly schema: Schema, private readonly rows: any[]) {
+    }
+
+    async read(params: JDataReadParams): Promise<JDataReadResult> {
+        return simpleRowArrayFilter(this.rows, params);
+    }
+}
+
+//endregion

package/src/jk_data/index.ts

@@ -1,166 +1,3 @@
-import {type Schema} from "jopi-toolkit/jk_schema";
-
-//region Rows Arrays
-
-export interface JFieldSorting {
-    id: string;
-    desc: boolean;
-}
-
-export interface JFieldFilter {
-    value?: string | number | boolean;
-    constraint: JFieldConstraintType;
-    caseSensitive?: boolean;
-}
-
-export type JFieldConstraintType =
-    | "$eq"    // Equals
-    | "$ne"    // Not equals
-    | "$gt"    // Greater than
-    | "$gte"   // Greater than or equals
-    | "$lt"    // Less than
-    | "$lte"   // Less than or equals
-    | "$in"    // In an array of values
-    | "$nin"   // Not in an array of values
-    | "$like"  // Like search %endsWith or startsWith%
-
-export interface JRowsFilter {
-    field?: string;
-    value: string;
-}
-
-export interface JPageExtraction {
-    pageIndex: number;
-    pageSize: number;
-}
-
-export interface JRowArrayFilter {
-    page?: JPageExtraction;
-    filter?: JRowsFilter;
-    sorting?: JFieldSorting[];
-    fieldFilters?: Record<string, JFieldFilter[]>;
-}
-
-/**
- * Filter the row content according to rules.
- */
-export function simpleRowArrayFilter(rows: any[], params: JRowArrayFilter): JTableDs_ReadResult {
-    // > Apply filter.
-
-    if (params.filter) {
-        const f = params.filter;
-
-        rows = rows.filter(r => {
-            if (f.field) {
-                let v = r[f.field];
-                if (v===undefined) return false;
-                return String(v).includes(f.value);
-            } else {
-                for (let v of Object.values(r)) {
-                    if (v===undefined) continue;
-                    if (String(v).includes(f.value)) return true;
-                }
-
-                return false;
-            }
-        });
-    }
-
-    // > Apply sorting.
-
-    if (params.sorting && params.sorting.length) {
-        const sorting = params.sorting[0];
-        const sortField = sorting.id;
-        const sortDesc = sorting.desc;
-
-        rows = rows.sort((a, b) => {
-            let av = a[sortField];
-            let bv = b[sortField];
-
-            if (av === undefined) av = "";
-            if (bv === undefined) bv = "";
-
-            const avIsNumber = typeof av === "number";
-            const bvIsNumber = typeof bv === "number";
-
-            if (avIsNumber && bvIsNumber) {
-                if (sortDesc) {
-                    return bv - av;
-                } else {
-                    return av - bv;
-                }
-            } else {
-                const avStr = String(av);
-                const bvStr = String(bv);
-
-                if (sortDesc) {
-                    return bvStr.localeCompare(avStr);
-                } else {
-                    return avStr.localeCompare(bvStr);
-                }
-            }
-        });
-    }
-
-    const totalWithoutPagination = rows.length;
-    let offset = 0;
-
-    if (params.page) {
-        offset = params.page.pageIndex * params.page.pageSize;
-        rows = rows.slice(offset, offset + params.page.pageSize);
-    }
-
-    return {rows, total: totalWithoutPagination, offset};
-}
-
-//endregion
-
-//region JTableDs
-
-export interface JTableDs_ReadParams extends JRowArrayFilter {
-}
-
-export interface JTableDs_ReadResult {
-    rows: any[];
-    total?: number;
-    offset?: number;
-}
-
-export interface JTableDs {
-    get name(): string;
-    get schema(): Schema;
-    read(params: JTableDs_ReadParams): Promise<JTableDs_ReadResult>;
-}
-
-export class JTableDs_UseArray implements JTableDs {
-    public constructor(public readonly name: string, public readonly schema: Schema, private readonly rows: any[]) {
-    }
-
-    async read(params: JTableDs_ReadParams): Promise<JTableDs_ReadResult> {
-        return simpleRowArrayFilter(this.rows, params);
-    }
-}
-
-export class JTableDs_HttpProxy implements JTableDs {
-    public constructor(public readonly name: string, private readonly url: string, public readonly schema: Schema) {
-    }
-
-    async read(params: JTableDs_ReadParams): Promise<JTableDs_ReadResult> {
-        let toSend = {dsName: this.name, read: params};
-
-        let res = await fetch(this.url, {
-            method: "POST",
-            headers: {"Content-Type": "application/json"},
-            body: JSON.stringify(toSend)
-        });
-
-        if (res.status !== 200) {
-            throw new Error(`Error while reading data source "${this.name}"`);
-        }
-
-        let asJson = await res.json();
-        return asJson as JTableDs_ReadResult;
-    }
-}
-
-//endregion
+export * from "./core.ts";
+export * from "./proxy.ts";
+export * from "./interfaces.ts";

package/src/jk_data/interfaces.ts

@@ -0,0 +1,140 @@
+import { type Schema } from "jopi-toolkit/jk_schema";
+import type {Translatable} from "../jk_tools";
+
+export interface JFieldSorting {
+    id: string;
+    desc: boolean;
+}
+
+export interface IActionContext {
+    refresh: () => void;
+}
+
+export interface JFieldFilter {
+    value?: string | number | boolean;
+    constraint: JFieldConstraintType;
+    caseSensitive?: boolean;
+}
+
+export type JFieldConstraintType =
+    | "$eq"    // Equals
+    | "$ne"    // Not equals
+    | "$gt"    // Greater than
+    | "$gte"   // Greater than or equals
+    | "$lt"    // Less than
+    | "$lte"   // Less than or equals
+    | "$in"    // In an array of values
+    | "$nin"   // Not in an array of values
+    | "$like"  // Like search %endsWith or startsWith%
+    ;
+
+export interface JGlobalFilter {
+    field?: string;
+    value: string;
+}
+
+export interface JPageExtraction {
+    pageIndex: number;
+    pageSize: number;
+}
+
+export interface JRowArrayFilter {
+    page?: JPageExtraction;
+    filter?: JGlobalFilter;
+    sorting?: JFieldSorting[];
+    fieldFilters?: Record<string, JFieldFilter[]>;
+}
+
+export interface JDataReadParams extends JRowArrayFilter {
+}
+
+export interface JDataReadResult {
+    rows: any[];
+    total?: number;
+    offset?: number;
+}
+
+export interface JActionDef {
+    id: string;
+    title?: Translatable;
+    separator?: boolean;
+}
+
+export interface JopiDataTable {
+    readonly schema: Schema;
+    readonly actions?: JActionDef[];
+    read(params: JDataReadParams): Promise<JDataReadResult>;
+}
+
+export interface JDataTable extends JopiDataTable {
+    readonly name: string;
+    executeAction?: (rows: any[], actionName: string, context?: IActionContext) => Promise<JActionResult | void>
+    isActionEnabled?: (actionName: string, rows: any[], context?: IActionContext) => boolean;
+}
+
+export interface JActionPreProcessParams {
+    rows: any[];
+    context?: IActionContext;
+}
+
+export interface JActionResult {
+    isOk?: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+    userMessage?: string;
+    data?: any;
+}
+
+export interface JActionPreProcessResult extends JActionResult {
+    rows?: any[];
+}
+
+export interface JActionPostProcessParams {
+    rows: any[];
+    context?: IActionContext;
+    
+    data?: any[];
+    userMessage?: string;
+}
+
+/**
+ * Defines the behavior of a custom action in the browser for a Jopi table.
+ * allowing to hook into the action lifecycle (pre-process, server call, post-process).
+ */
+export interface JopiTableBrowserActionItem {
+    /**
+     * Callback invoked when an error occurs during the action execution.
+     * This can be triggered by a failure in the `action` handler or a server-side error.
+     */
+    onError?: (params: JActionResult) => Promise<void>,
+
+    /**
+     * The main client-side action handler.
+     * - Can be used to perform checks or data transformation before sending to the server.
+     * - Can be used as a standalone action if `disableServerCall` is true.
+     * - Return `void` to proceed with the default flow.
+     * - Return a `JActionPreProcessResult` to control flow (e.g., stop execution if `isOk` is false) or modify data sent to server.
+     */
+    action?: (params: JActionPreProcessParams) => Promise<JActionPreProcessResult|void>,
+
+    /**
+     * Callback invoked after the server-side action has successfully completed.
+     * Useful for showing notifications, refreshing data, or triggering other UI updates.
+     */
+    afterServerCall?: (params: JActionPostProcessParams) => Promise<void>;
+
+    /**
+     * Function to determine if the action should be enabled/clickable.
+     * Based on the currently selected rows and the current action context.
+     * If not provided, the action is assumed to be always enabled.
+     */
+    canEnable?: (rows: any[], context?: IActionContext) => boolean;
+
+    /**
+     * If set to true, the framework will NOT assume there is a corresponding server-side action to call.
+     * Use this for actions that are purely client-side (e.g., "Copy to clipboard").
+     */
+    disableServerCall?: boolean;
+}
+
+export type JopiTableBrowserActions = Record<string, JopiTableBrowserActionItem>

package/src/jk_data/proxy.ts

@@ -0,0 +1,102 @@
+import type { IActionContext, JopiTableBrowserActions, JDataReadParams, JDataReadResult, JDataTable, JActionDef, JActionResult } from "./interfaces.ts";
+import { schema, type Schema } from "jopi-toolkit/jk_schema";
+
+export interface ProxyParams {
+    name: string;
+    apiUrl: string;
+    actions?: JActionDef[];
+    schema: { meta: any; desc: any; };
+}
+
+export class Proxy implements JDataTable {
+    readonly name: string;
+    readonly schema: Schema;
+    readonly actions?: JActionDef[];
+    private readonly url: string;
+
+    readonly browserActions: JopiTableBrowserActions;
+    
+    constructor(params: ProxyParams, browserActions: JopiTableBrowserActions) {
+        this.name = params.name;
+        this.url = params.apiUrl;
+        this.actions = params.actions;
+        this.schema = schema(params.schema.desc, params.schema.meta);
+        this.browserActions = browserActions;
+    }
+
+    async read(params: JDataReadParams): Promise<JDataReadResult> {
+        const asJson = await this.callServer({ dsName: this.name, read: params });
+        return asJson as JDataReadResult;
+    }
+
+    isActionEnabled(actionName: string, rows: any[], context?: IActionContext): boolean {
+        let actionEntry = this.browserActions[actionName];
+        if (!actionEntry) return false;
+        if (!actionEntry.canEnable) return true;
+        return actionEntry.canEnable(rows, context);
+    }
+
+    async executeAction(rows: any[], actionName: string, context?: IActionContext): Promise<JActionResult|void> {
+        async function processError(res: JActionResult | undefined) {
+            if (!res) return true;
+            
+            if (res.isOk===false||res.errorCode||res.errorMessage) {
+                if (actionEntry.onError) {
+                    await actionEntry.onError(res);
+                    return false;
+                }
+            }
+            
+            return true;
+        }
+
+        let actionEntry = this.browserActions[actionName];
+        if (!actionEntry) return;
+
+        if (actionEntry.action) {
+            let res = await actionEntry.action({ rows, context });
+
+            if (res) {
+                if (!processError(res)) return;
+
+                if (res.rows !== undefined) {
+                    rows = res.rows;
+                }
+            }
+        }
+
+        if (actionEntry.disableServerCall === true) {
+            return;
+        }
+         
+        let serverRes = await this.callServer({ action: actionName, rows });
+        if (!processError(serverRes)) return;
+
+        if (actionEntry.afterServerCall) {
+            await actionEntry.afterServerCall({
+                rows,
+                context,
+                data: serverRes?.data,
+                userMessage: serverRes?.userMessage
+            });
+        }
+    }
+
+    async callServer(data: any): Promise<any> {
+        let res = await fetch(this.url, {
+            method: "POST",
+            headers: {"Content-Type": "application/json"},
+            body: JSON.stringify(data)
+        });
+
+        if (res.status !== 200) {
+            throw new Error(`Error while calling data source "${this.name}"`);
+        }
+
+        return await res.json();
+    }
+}
+
+export function toDataTableProxy(params: ProxyParams, browserActions?: JopiTableBrowserActions): JDataTable {
+    return new Proxy(params, browserActions || {});
+}

package/src/jk_dates/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Calculate week-number from a date.
+ */
+export function calcWeekNumber(year: number, month: number, day: number): number {
+    const date = new Date(Date.UTC(year, month - 1, day));
+    const dayNum = date.getUTCDay() || 7;
+
+    date.setUTCDate(date.getUTCDate() + (4 - dayNum));
+    const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
+
+    return Math.ceil((((date.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
+}

package/src/jk_fs/jBundler_ifServer.ts

@@ -1,7 +1,7 @@
 // noinspection JSUnusedGlobalSymbols
 
 import fs from "node:fs/promises";
-import fss, {createReadStream, createWriteStream} from "node:fs";
+import fss, {createReadStream} from "node:fs";
 import {fileURLToPath as n_fileURLToPath, pathToFileURL as n_pathToFileURL } from "node:url";
 import {lookup} from "mime-types";
 import {Readable} from "node:stream";
@@ -172,6 +172,15 @@ export async function writeTextToFile(filePath: string, text: string, createDir:
     await fs.writeFile(filePath, text, {encoding: 'utf8', flag: 'w'});
 }
 
+export async function appendTextToFile(filePath: string, text: string): Promise<void> {
+    try {
+        await fs.appendFile(filePath, text, {encoding: 'utf8'});
+    } catch {
+        await mkDir(path.dirname(filePath));
+        await fs.appendFile(filePath, text, {encoding: 'utf8'});
+    }
+}
+
 export function writeTextToFileSync(filePath: string, text: string, createDir: boolean = true): void {
     if (createDir) {
         try {
@@ -516,6 +525,7 @@ export const join = path.join;
 export const resolve = path.resolve;
 export const dirname = path.dirname;
 export const extname = path.extname;
+export const relative = path.relative;
 
 export const sep = path.sep;
 export const isAbsolute = path.isAbsolute;

package/src/jk_memcache/index.ts

@@ -202,18 +202,14 @@ export class JkMemCache {
   /**
    * Retrieve an item from the cache with its metadata.
    */
-  public getWithMeta<T = any>(key: string, peek = false): { value: T; meta: any } | null {
+  public getWithMeta<T = any>(key: string, peek = false): { value: T; meta: any; size: number } | null {
     const entry = this._storage.get(key);
+    
     if (!entry) return null;
-
-    if (entry.expiresAt && entry.expiresAt < Date.now()) {
-      this.delete(key);
-      return null;
-    }
-
     if (!peek) entry.accessCount++;
 
     let value: T;
+    
     if (entry.type === 'buffer') {
       value = entry.value as T;
     } else if (entry.type === 'json') {
@@ -222,7 +218,7 @@ export class JkMemCache {
       value = entry.value as T;
     }
 
-    return { value, meta: entry.meta };
+    return { value, meta: entry.meta, size: entry.size };
   }
 
   /**