@adula/kit 0.2.0-alpha.4 → 1.2.0

package/build/src/admin/record_title.js

@@ -0,0 +1,50 @@
+const TITLE_TYPES = new Set(['string', 'text', 'integer', 'money', 'date', 'datetime', 'lookup']);
+/**
+ * The fields that name a record wherever it is referenced (#47, #32): the resource's
+ * `title`, or else its first sequence field and its first text field in `list`. Lookup
+ * keys are never shown raw; declared lookup fields are shown by their Arabic label.
+ */
+export function titleFields(resource) {
+    if (resource.title)
+        return [...resource.title];
+    const sequence = Object.keys(resource.fields).find((key) => resource.fields[key].sequence);
+    const text = resource.list.find((key) => {
+        const field = resource.fields[key];
+        return (field.type === 'string' || field.type === 'text') && !field.sequence;
+    });
+    return [sequence, text].filter((key) => key !== undefined);
+}
+/** Definition check: title fields exist, are readable and have a displayable type. */
+export function assertTitle(resource) {
+    if (!resource.title)
+        return;
+    if (!resource.title.length)
+        throw new Error(`${resource.name}: title needs at least one field`);
+    const readable = new Set(resource.serialize ?? [...resource.list, ...resource.show]);
+    for (const key of resource.title) {
+        const field = resource.fields[key];
+        if (!field)
+            throw new Error(`Unknown field: ${key}`);
+        if (!TITLE_TYPES.has(field.type))
+            throw new Error(`${resource.name}: title field ${key} cannot be a ${field.type}`);
+        if (!readable.has(key))
+            throw new Error(`${resource.name}: title field ${key} must be serialized`);
+    }
+}
+/**
+ * The title of one serialized record, read after field-level filtering so it never shows
+ * a value the viewer may not read. Returns null when no title field has a value.
+ */
+export function formatTitle(resource, record, lookupLabel) {
+    const parts = [];
+    for (const key of titleFields(resource)) {
+        const value = record[key];
+        if (value === null || value === undefined || value === '')
+            continue;
+        const field = resource.fields[key];
+        parts.push(field.type === 'lookup'
+            ? (lookupLabel(field.group, String(value)) ?? String(value))
+            : String(value));
+    }
+    return parts.length ? parts.join(' · ') : null;
+}

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

@@ -1,8 +1,27 @@
 import type { Knex } from 'knex';
 import type { ResourceRegistry } from '../resource/registry.js';
-import type { Action, RecordData, Resource, SerializedRecord } from '../resource/types.js';
+import type { Action, JsonValue, RecordData, Resource, SerializedRecord } from '../resource/types.js';
 import { type Actor, type KitAbility } from '../auth/ability.js';
+import { type Conditions } from '../auth/conditions.js';
 import type { ResourceDescription, ResourceNavigation, ResourceField } from './presentation.js';
+export type AggregateOptions = {
+    /** Up to three queryable fields (docStatus and orgUnitId are also accepted). */
+    groupBy?: string[];
+    /** Count rows per group (default true). */
+    count?: boolean;
+    /** Integer or money fields to total per group; money totals are decimal strings. */
+    sum?: string[];
+    /** Equality filters, as in list(). */
+    filters?: Record<string, unknown>;
+    /** Role-rule style conditions ($eq, $ne, $in, $lt, $gt, $like, "$actor.id"). */
+    where?: Conditions;
+    search?: string;
+};
+export type AggregateRow = {
+    group: Record<string, JsonValue>;
+    count?: number;
+    sum?: Record<string, string | null>;
+};
 export type ListOptions = {
     limit?: number;
     cursor?: string;
@@ -10,6 +29,8 @@ export type ListOptions = {
     sort?: string;
     direction?: 'asc' | 'desc';
     filters?: Record<string, unknown>;
+    /** Only records carrying this tag (see RecordCollaboration.setTags). */
+    tag?: string;
     estimate?: boolean;
 };
 /**
@@ -17,10 +38,30 @@ export type ListOptions = {
  * indirectly, so it needs unconditional view access at the field's level.
  */
 export declare function canQueryField(resource: Resource, actor: Actor, ability: KitAbility, key: string): boolean;
+/** Options of ResourceService.systemSave. */
+export type SystemSaveOptions = {
+    /** The user recorded as the author: created/updated by, activity and events. */
+    actorId: number;
+    /** Write inside the module's transaction. */
+    trx?: Knex.Transaction;
+    /** Why module code wrote the record; stored with the activity entry. */
+    reason?: string;
+    /** Optimistic lock: when given, it must match the stored version. */
+    version?: number;
+    /**
+     * The person who chose the values, when module code writes a choice made by a user,
+     * such as a supervisor reassigning a record. A new value of a user field must then be
+     * eligible for them as in a user save; without it, any active member qualifies on
+     * unscoped resources.
+     */
+    chooser?: Actor;
+};
 export declare class ResourceService {
     private db;
     private registry;
     constructor(db: Knex, registry: ResourceRegistry);
+    /** The Arabic label of a registered resource, for notifications and titles. */
+    label(name: string): string;
     /** Project navigation is derived from registered resources and the current actor. */
     navigation(actor: Actor): ResourceNavigation;
     describe(name: string, actor: Actor): ResourceDescription;
@@ -33,7 +74,20 @@ export declare class ResourceService {
     private scopedQuery;
     private columns;
     private find;
+    /** A live record regardless of any actor's scope, for system writes. */
+    private findAny;
     private requireRecord;
+    /**
+     * Authorizes one record for collaboration features (comments, tags, assignments...).
+     * Scope and conditional rules apply exactly as for show/update.
+     */
+    access(name: string, id: number, actor: Actor, action?: Action, db?: Knex): Promise<{
+        resource: Resource;
+        record: RecordData;
+        ability: KitAbility;
+    }>;
+    /** Whether a (possibly other) actor may perform an action on a record; never throws for denial. */
+    permits(name: string, id: number, actor: Actor, action?: Action): Promise<boolean>;
     list(name: string, actor: Actor, options?: ListOptions): Promise<{
         data: SerializedRecord[];
         permissions: {
@@ -47,7 +101,24 @@ export declare class ResourceService {
         related: Record<string, SerializedRecord[]>;
     }>;
     private canQueryField;
+    /**
+     * Counts and totals over the records the actor may view, grouped by queryable fields,
+     * for dashboards. Authorization is list()'s: the same rules, organization scope and
+     * soft-delete filter apply, and every grouped, totalled or filtered field must be one
+     * the actor may query (E_FIELD_FORBIDDEN otherwise), so no hidden value leaks.
+     */
+    aggregate(name: string, actor: Actor, options?: AggregateOptions): Promise<{
+        rows: AggregateRow[];
+        truncated: boolean;
+    }>;
     private preload;
+    /** Formats record titles of one resource, loading the labels of its title lookups once. */
+    private titler;
+    /**
+     * Titles of records the actor may view, read under the actor's field access (#32).
+     * Records the actor cannot view are left out; callers fall back to the record id.
+     */
+    titles(name: string, ids: readonly number[], actor: Actor): Promise<Map<number, string>>;
     show(name: string, id: number, actor: Actor): Promise<{
         data: SerializedRecord;
         permissions: Partial<Record<Action, boolean>>;
@@ -57,6 +128,10 @@ export declare class ResourceService {
         id?: number;
         search?: string;
         cursor?: string;
+        /** User fields: the organization unit chosen in the form. */
+        orgUnitId?: number;
+        /** User fields: choices for a list filter instead of a form. */
+        purpose?: 'form' | 'filter';
     }): Promise<{
         data: {
             value: string;
@@ -64,11 +139,25 @@ export declare class ResourceService {
         }[];
         nextCursor: string | null;
     }>;
+    /**
+     * Choices for a user field. A form lists active members of the record's unit or its
+     * ancestors (the users the record is visible to through membership); a filter lists
+     * active users who share organization scope with the actor. Only names are returned.
+     */
+    private userOptions;
+    /**
+     * Active users eligible for a user field: members of the unit at `path` or of one of
+     * its ancestors, or (without a path) users sharing organization scope with the actor.
+     * A system write on an unscoped resource passes no actor: any active member qualifies.
+     */
+    private eligibleUsers;
     /** 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;
     }>>;
+    /** Inline children of an already authorized parent record. */
+    private childrenOf;
     /** Active lookup labels for the lookup fields the actor may read on this resource. */
     lookups(name: string, actor: Actor): Promise<Record<string, {
         value: string;
@@ -88,10 +177,66 @@ export declare class ResourceService {
         actorEmail: string | null;
         createdAt: string;
     }[]>;
-    editor(name: string, actor: Actor, id?: number): Promise<{
+    /**
+     * Inline children and recent activity of one record, authorized with a single record
+     * read (for deferred page props that would otherwise read the record twice).
+     */
+    details(name: string, id: number, actor: Actor): Promise<{
+        children: Record<string, {
+            rows: SerializedRecord[];
+            hasMore: boolean;
+        }>;
+        activity: {
+            id: number;
+            action: Action;
+            fields: string[];
+            actorId: number;
+            actorName: string | null;
+            /**
+             * @deprecated Always null. Kept so project-owned copies of resource-show from
+             * earlier releases still compile; they fall back to the actor id.
+             */
+            actorEmail: string | null;
+            createdAt: string;
+        }[];
+    }>;
+    /** show(), children() and activity() of one record from a single record read. */
+    record(name: string, id: number, actor: Actor): Promise<{
+        data: SerializedRecord;
+        permissions: Partial<Record<Action, boolean>>;
+        related: Record<string, SerializedRecord[]>;
+        children: Record<string, {
+            rows: SerializedRecord[];
+            hasMore: boolean;
+        }>;
+        activity: {
+            id: number;
+            action: Action;
+            fields: string[];
+            actorId: number;
+            actorName: string | null;
+            /**
+             * @deprecated Always null. Kept so project-owned copies of resource-show from
+             * earlier releases still compile; they fall back to the actor id.
+             */
+            actorEmail: string | null;
+            createdAt: string;
+        }[];
+    }>;
+    private activityOf;
+    /**
+     * The form description for create (no id) or update. `defaults` pre-fills a create form
+     * (#48), for example `?defaults[violation]=13`: only visible form fields are used, a
+     * related record must be viewable by the actor and a lookup must be active. Anything else
+     * is dropped. Defaults are only initial values; saving validates as usual.
+     */
+    editor(name: string, actor: Actor, id?: number, request?: {
+        defaults?: Record<string, unknown>;
+    }): Promise<{
         mode: string;
         name: string;
         label: string;
+        recordLabel: string | null;
         fields: ({
             label: import("../resource/types.js").Label;
             column?: string;
@@ -131,6 +276,18 @@ export declare class ResourceService {
             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: "user";
+            key: string;
         } | {
             label: import("../resource/types.js").Label;
             column?: string;
@@ -160,6 +317,8 @@ export declare class ResourceService {
             group: string;
             key: string;
         })[];
+        /** Initial values of a create form, already checked against the actor's access. */
+        defaults: SerializedRecord;
         inline: Record<string, {
             rows: SerializedRecord[];
             hasMore: boolean;
@@ -182,13 +341,36 @@ export declare class ResourceService {
             label: string;
         }[];
         scoped: boolean;
+        /** The belongsTo field whose record decides the unit; the form shows no unit picker. */
+        scopeFrom: string | null;
         record: SerializedRecord | null;
     }>;
     save(name: string, actor: Actor, input: RecordData, id?: number, transaction?: Knex.Transaction): Promise<SerializedRecord>;
+    /**
+     * A write decided by module code rather than by a user's role rules: state transitions,
+     * snapshots and listener updates. It runs the validator, hooks, lookup, relation and
+     * attachment checks, versioning and the audit trail exactly like save(), and skips only
+     * the actor's role rules and organization scope. Values may set any stored field except
+     * sequences and inline children. Updates merge the given values into the stored record.
+     * Returns the full stored record; module code must not send it to users unfiltered.
+     */
+    systemSave(name: string, values: RecordData, id: number | undefined, options: SystemSaveOptions): Promise<RecordData>;
+    /**
+     * Moves the records whose scope follows this parent (`scope: { from }`) to the parent's
+     * current organization unit, through systemSave. Call it from a listener on the parent's
+     * `updated` event, or right after moving the parent. Returns the number of moved records.
+     */
+    rehome(parentName: string, parentId: number, options: Omit<SystemSaveOptions, 'version'>): Promise<number>;
     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>;
+    /**
+     * Amend-by-copy: a cancelled document is copied into a new draft that points to
+     * it through amended_from_id, together with its inline lines. The original stays
+     * cancelled and unchanged; sequence fields receive new numbers.
+     */
+    amend(name: string, id: number, actor: Actor, transaction?: Knex.Transaction): Promise<SerializedRecord>;
     private audit;
 }