@adula/kit 0.2.0-alpha.1

package/build/src/admin/contracts.js

@@ -0,0 +1,93 @@
+import { subject } from '@casl/ability';
+import { conditionFields } from '../auth/ability.js';
+import { columnName } from '../resource/define_resource.js';
+import { KitError } from './errors.js';
+const standard = ['id', 'createdBy', 'updatedBy', 'createdAt', 'updatedAt', 'deletedAt'];
+export function selectedFields(resource, ability, options = {}) {
+    return [
+        ...new Set([
+            ...standard,
+            ...(resource.scoped ? ['orgUnitId'] : []),
+            ...(resource.version ? ['version'] : []),
+            ...(resource.submittable ? ['docStatus', 'amendedFromId'] : []),
+            ...(options.write
+                ? Object.keys(resource.fields)
+                : (resource.serialize ?? [...resource.list, ...resource.show])),
+            ...Object.keys(resource.fields).filter((k) => resource.fields[k].type === 'belongsTo'),
+            ...(options.extra ?? []),
+            ...conditionFields(ability, resource),
+        ]),
+    ].filter((key) => key !== 'orgPath' && resource.fields[key]?.type !== 'hasMany');
+}
+export function fromRow(row, resource) {
+    const result = {};
+    for (const key of [
+        ...standard,
+        'orgUnitId',
+        'version',
+        'docStatus',
+        'amendedFromId',
+        'orgPath',
+        ...Object.keys(resource.fields),
+    ]) {
+        const column = resource.fields[key]?.column ?? columnName(key);
+        if (column in row) {
+            const value = row[column];
+            result[key] =
+                value instanceof Date
+                    ? resource.fields[key]?.type === 'date'
+                        ? // pg parses DATE as local midnight. Preserve its calendar day;
+                            // converting to UTC first shifts it in positive-offset time zones.
+                            `${String(value.getFullYear()).padStart(4, '0')}-${String(value.getMonth() + 1).padStart(2, '0')}-${String(value.getDate()).padStart(2, '0')}`
+                        : value.toISOString()
+                    : value;
+        }
+    }
+    return result;
+}
+export function jsonValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(jsonValue);
+    if (typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, jsonValue(entry)]));
+    throw new Error('Non-serializable resource value');
+}
+export function serialize(resource, record, ability, actor) {
+    const result = { id: jsonValue(record.id) };
+    const fields = resource.serialize ?? [...new Set([...resource.list, ...resource.show])];
+    for (const key of fields) {
+        const minimum = Math.max(resource.fields[key]?.permissionLevel ?? 0, resource.hidden?.includes(key) ? 1 : 0);
+        if (actor.permissionLevel >= minimum &&
+            ability.can('view', subject(resource.name, record), key) &&
+            key in record)
+            result[key] = jsonValue(record[key]);
+    }
+    if (resource.version)
+        result.version = jsonValue(record.version);
+    if (resource.submittable)
+        result.docStatus = jsonValue(record.docStatus);
+    if (resource.scoped)
+        result.orgUnitId = jsonValue(record.orgUnitId);
+    return result;
+}
+export function writableInput(resource, input) {
+    const allowed = new Set([
+        ...resource.form,
+        ...(resource.scoped ? ['orgUnitId'] : []),
+        ...(resource.version ? ['version'] : []),
+    ]);
+    for (const key of Object.keys(input))
+        if (!allowed.has(key))
+            throw new KitError(422, 'E_FIELD_NOT_WRITABLE', `Field is not writable: ${key}`);
+    return Object.fromEntries(Object.entries(input).filter(([key]) => resource.form.includes(key)));
+}

package/build/src/admin/controller.d.ts

@@ -0,0 +1,30 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { Actor } from '../auth/ability.js';
+import type { ResourceRegistry } from '../resource/registry.js';
+import type { Resource } from '../resource/types.js';
+import type { ResourceService } from './resource_service.js';
+export type ResourceRuntime = {
+    registry: ResourceRegistry;
+    resources: ResourceService;
+    actor: Actor;
+};
+export type ResourceList = Awaited<ReturnType<ResourceService['list']>>;
+export type ResourceEditor = Awaited<ReturnType<ResourceService['editor']>>;
+export type ResourceShow = Awaited<ReturnType<ResourceService['show']>>;
+export type ResourceChildren = Awaited<ReturnType<ResourceService['children']>>;
+export type ResourceLookups = Awaited<ReturnType<ResourceService['lookups']>>;
+export type ResourceActivity = Awaited<ReturnType<ResourceService['activity']>>;
+export interface ResourceController {
+    index(ctx: HttpContext): Promise<unknown>;
+    show(ctx: HttpContext): Promise<unknown>;
+    store(ctx: HttpContext): Promise<unknown>;
+    update(ctx: HttpContext): Promise<unknown>;
+    destroy(ctx: HttpContext): Promise<unknown>;
+    submit(ctx: HttpContext): Promise<unknown>;
+    cancel(ctx: HttpContext): Promise<unknown>;
+    create(ctx: HttpContext): Promise<unknown>;
+    edit(ctx: HttpContext): Promise<unknown>;
+    options(ctx: HttpContext): Promise<unknown>;
+}
+/** The host supplies its authenticated actor; ResourceService authorizes every action. */
+export declare function createResourceController(resolveRuntime: (ctx: HttpContext) => Promise<ResourceRuntime>, renderList?: (ctx: HttpContext, resource: Resource, result: ResourceList) => unknown, renderForm?: (ctx: HttpContext, resource: Resource, editor: ResourceEditor) => unknown, renderShow?: (ctx: HttpContext, resource: Resource, result: ResourceShow) => unknown): new () => ResourceController;

package/build/src/admin/controller.js

@@ -0,0 +1,116 @@
+import { KitError } from './errors.js';
+/** The host supplies its authenticated actor; ResourceService authorizes every action. */
+export function createResourceController(resolveRuntime, renderList, renderForm, renderShow) {
+    return class ResourcesController {
+        async create(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => {
+                const editor = await resources.editor(resource.name, actor);
+                return renderForm && ctx.request.accepts(['html', 'json']) === 'html'
+                    ? renderForm(ctx, resource, editor)
+                    : editor;
+            });
+        }
+        async edit(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => {
+                const editor = await resources.editor(resource.name, actor, this.#id(ctx));
+                return renderForm && ctx.request.accepts(['html', 'json']) === 'html'
+                    ? renderForm(ctx, resource, editor)
+                    : editor;
+            });
+        }
+        async index(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => {
+                const result = await resources.list(resource.name, actor, {
+                    limit: ctx.request.input('limit'),
+                    cursor: ctx.request.input('cursor'),
+                    search: ctx.request.input('search'),
+                    sort: ctx.request.input('sort'),
+                    direction: ctx.request.input('direction'),
+                    filters: ctx.request.input('filters'),
+                    estimate: ctx.request.input('estimate') !== 'false' && ctx.request.input('estimate') !== false,
+                });
+                return renderList && ctx.request.accepts(['html', 'json']) === 'html'
+                    ? renderList(ctx, resource, result)
+                    : result;
+            });
+        }
+        async show(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => {
+                const result = await resources.show(resource.name, this.#id(ctx), actor);
+                return renderShow && ctx.request.accepts(['html', 'json']) === 'html'
+                    ? renderShow(ctx, resource, result)
+                    : result;
+            });
+        }
+        async options(ctx) {
+            return this.#execute(ctx, ({ resources, actor }, resource) => resources.relationOptions(resource.name, ctx.params.field, actor, {
+                id: ctx.request.input('id') === undefined
+                    ? undefined
+                    : this.#positiveId(ctx.request.input('id')),
+                search: ctx.request.input('search'),
+                cursor: ctx.request.input('cursor'),
+            }));
+        }
+        async store(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => ctx.response.created({
+                data: await resources.save(resource.name, actor, ctx.request.body()),
+            }));
+        }
+        async update(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => ({
+                data: await resources.save(resource.name, actor, ctx.request.body(), this.#id(ctx)),
+            }));
+        }
+        async destroy(ctx) {
+            return this.#transition(ctx, 'delete');
+        }
+        async submit(ctx) {
+            return this.#transition(ctx, 'submit');
+        }
+        async cancel(ctx) {
+            return this.#transition(ctx, 'cancel');
+        }
+        #id(ctx) {
+            return this.#positiveId(ctx.params.id);
+        }
+        #positiveId(value) {
+            const id = Number(value);
+            if (!Number.isSafeInteger(id) || id <= 0)
+                throw new KitError(404, 'E_NOT_FOUND', 'السجل غير موجود');
+            return id;
+        }
+        async #transition(ctx, action) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => ({
+                data: await resources.transition(resource.name, this.#id(ctx), actor, action, ctx.request.input('version')),
+            }));
+        }
+        async #execute(ctx, action) {
+            try {
+                const runtime = await resolveRuntime(ctx);
+                let resource;
+                try {
+                    resource = runtime.registry.get(ctx.params.resource);
+                }
+                catch {
+                    throw new KitError(404, 'E_NOT_FOUND', 'الكيان غير موجود');
+                }
+                return await action(runtime, resource);
+            }
+            catch (error) {
+                if (error instanceof KitError)
+                    return ctx.response
+                        .status(error.status)
+                        .send({ error: { code: error.code, message: error.message } });
+                if (error?.code === '23505')
+                    return ctx.response.conflict({
+                        error: { code: 'E_DUPLICATE', message: 'هذه القيمة مستخدمة في سجل آخر' },
+                    });
+                if (error?.code === '23503')
+                    return ctx.response.unprocessableEntity({
+                        error: { code: 'E_RELATION', message: 'تحقق من السجلات المرتبطة' },
+                    });
+                throw error;
+            }
+        }
+    };
+}

package/build/src/admin/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class KitError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}

package/build/src/admin/errors.js

@@ -0,0 +1,9 @@
+export class KitError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}

package/build/src/admin/presentation.d.ts

@@ -0,0 +1,22 @@
+import type { Action, Field } from '../resource/types.js';
+export type ResourceField = Field & {
+    key: string;
+};
+export type RecordPermissions = Partial<Record<Action, boolean>>;
+export type ResourceDescription = {
+    name: string;
+    label: string;
+    fields: ResourceField[];
+    list: string[];
+    show: string[];
+    searchable: boolean;
+    canCreate: boolean;
+    scoped: boolean;
+    submittable: boolean;
+};
+export type ResourceNavigation = {
+    name: string;
+    label: string;
+    href: string;
+    module: string;
+}[];

package/build/src/admin/presentation.js

@@ -0,0 +1 @@
+export {};

package/build/src/admin/resource_service.d.ts

@@ -0,0 +1,170 @@
+import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
+import type { Action, RecordData, SerializedRecord } from '../resource/types.js';
+import { type Actor } from '../auth/ability.js';
+import type { ResourceDescription, ResourceNavigation, ResourceField } from './presentation.js';
+export type ListOptions = {
+    limit?: number;
+    cursor?: string;
+    search?: string;
+    sort?: string;
+    direction?: 'asc' | 'desc';
+    filters?: Record<string, unknown>;
+    estimate?: boolean;
+};
+export declare class ResourceService {
+    private db;
+    private registry;
+    constructor(db: Knex, registry: ResourceRegistry);
+    /** Project navigation is derived from registered resources and the current actor. */
+    navigation(actor: Actor): ResourceNavigation;
+    describe(name: string, actor: Actor): ResourceDescription;
+    private permissions;
+    private normalizeValues;
+    /** Stored attachment ids become summaries for readers; copies keep policy checks on raw rows. */
+    private hydrate;
+    private hydrateOne;
+    private authorizeAction;
+    private scopedQuery;
+    private columns;
+    private find;
+    private requireRecord;
+    list(name: string, actor: Actor, options?: ListOptions): Promise<{
+        data: SerializedRecord[];
+        permissions: {
+            [k: string]: Partial<Record<Action, boolean>>;
+        };
+        meta: {
+            limit: number;
+            estimatedTotal: number | undefined;
+            nextCursor: string | null;
+        };
+        related: Record<string, SerializedRecord[]>;
+    }>;
+    private canQueryField;
+    private preload;
+    show(name: string, id: number, actor: Actor): Promise<{
+        data: SerializedRecord;
+        permissions: Partial<Record<Action, boolean>>;
+        related: Record<string, SerializedRecord[]>;
+    }>;
+    relationOptions(name: string, key: string, actor: Actor, options?: {
+        id?: number;
+        search?: string;
+        cursor?: string;
+    }): Promise<{
+        data: {
+            value: string;
+            label: string;
+        }[];
+        nextCursor: string | null;
+    }>;
+    /** Deferred relation reads re-authorize the parent and each child on every request. */
+    children(name: string, id: number, actor: Actor): Promise<Record<string, {
+        rows: SerializedRecord[];
+        hasMore: boolean;
+    }>>;
+    /** Active lookup labels for the lookup fields the actor may read on this resource. */
+    lookups(name: string, actor: Actor): Promise<Record<string, {
+        value: string;
+        label: string;
+    }[]>>;
+    /** The last 50 recorded mutations of one record, after authorizing the record itself. */
+    activity(name: string, id: number, actor: Actor): Promise<{
+        id: number;
+        action: Action;
+        fields: string[];
+        actorId: number;
+        actorEmail: string | null;
+        createdAt: string;
+    }[]>;
+    editor(name: string, actor: Actor, id?: number): Promise<{
+        mode: string;
+        name: string;
+        label: string;
+        fields: ({
+            label: import("../resource/types.js").Label;
+            column?: string;
+            required?: boolean;
+            unique?: boolean;
+            sortable?: boolean;
+            searchable?: boolean;
+            filterable?: boolean;
+            permissionLevel?: number;
+            sequence?: string;
+            type: "string" | "text" | "integer" | "money" | "boolean" | "date" | "datetime" | "json" | "attachment";
+            key: string;
+        } | {
+            label: import("../resource/types.js").Label;
+            column?: string;
+            required?: boolean;
+            unique?: boolean;
+            sortable?: boolean;
+            searchable?: boolean;
+            filterable?: boolean;
+            permissionLevel?: number;
+            sequence?: string;
+            type: "belongsTo";
+            resource: string;
+            key: string;
+        } | {
+            label: import("../resource/types.js").Label;
+            column?: string;
+            required?: boolean;
+            unique?: boolean;
+            sortable?: boolean;
+            searchable?: boolean;
+            filterable?: boolean;
+            permissionLevel?: number;
+            sequence?: string;
+            type: "hasMany";
+            resource: string;
+            foreignKey: string;
+            inline?: boolean;
+            key: string;
+        } | {
+            label: import("../resource/types.js").Label;
+            column?: string;
+            required?: boolean;
+            unique?: boolean;
+            sortable?: boolean;
+            searchable?: boolean;
+            filterable?: boolean;
+            permissionLevel?: number;
+            sequence?: string;
+            type: "lookup";
+            group: string;
+            key: string;
+        })[];
+        inline: Record<string, {
+            rows: SerializedRecord[];
+            hasMore: boolean;
+            canCreate: boolean;
+            permissions: Record<string, {
+                update: boolean;
+                delete: boolean;
+            }>;
+            fields: ResourceField[];
+            createFields: string[];
+            updateFields: Record<string, string[]>;
+        }>;
+        options: Record<string, {
+            value: string;
+            label: string;
+        }[]>;
+        relationSearch: Record<string, boolean>;
+        orgUnits: {
+            value: string;
+            label: string;
+        }[];
+        scoped: boolean;
+        record: SerializedRecord | null;
+    }>;
+    save(name: string, actor: Actor, input: RecordData, id?: number, transaction?: Knex.Transaction): Promise<SerializedRecord>;
+    private persist;
+    private requireVersion;
+    /** Inline children share the parent's draft state, organization and update authority. */
+    private requireInlineParents;
+    transition(name: string, id: number, actor: Actor, action: 'delete' | 'submit' | 'cancel', version?: unknown, transaction?: Knex.Transaction): Promise<SerializedRecord>;
+    private audit;
+}