@fabriktor/fx 0.0.105 → 0.0.106

package/dist/src/billable/billable.d.ts

@@ -26,7 +26,24 @@ type VendorInvoiceInsertOptions = Parameters<BillableOperator["insertOneVendorIn
 type VendorInvoiceReplaceOptions = Parameters<BillableOperator["replaceOneVendorInvoice"]>[0];
 type WarehouseInsertOptions = Parameters<BillableOperator["insertOneWarehouse"]>[0];
 type WarehouseReplaceOptions = Parameters<BillableOperator["replaceOneWarehouse"]>[0];
-export type SearchBillsOptions = OwnerSearchOptions & Partial<Pick<Bill, "is_estimate" | "is_canceled" | "type">>;
+export declare const BillFilter: {
+    readonly All: "all";
+    readonly NotCancelled: "not_cancelled";
+    readonly Fixed: "fixed";
+    readonly Dynamic: "dynamic";
+    readonly Cancelled: "cancelled";
+};
+export type BillFilter = (typeof BillFilter)[keyof typeof BillFilter];
+export declare function billFilterFields(value: BillFilter): Partial<Pick<Bill, "is_canceled" | "type">>;
+type ItemSearchFields = Partial<Pick<Item, "folder_id" | "is_archived" | "quantifier_id">> & {
+    warehouse_id?: Item["per_warehouse_quantity"][number]["warehouse_id"];
+};
+type EquipmentSearchFields = Partial<Pick<Equipment, "folder_id" | "is_archived" | "warehouse_id" | "rental_type">>;
+type ChargeSearchFields = Partial<Pick<Charge, "location_id" | "entity_id" | "warehouse_id" | "type" | "is_estimate" | "is_billed">>;
+type MeterReadingSearchFields = Partial<Pick<MeterReading, "location_id" | "equipment_id">>;
+export type SearchBillsOptions = OwnerSearchOptions & Partial<Pick<Bill, "is_estimate" | "is_canceled" | "type">> & {
+    filter?: BillFilter;
+};
 export type SearchBillsPage = SearchPage<Bill>;
 export type CreateBillableFolderOptions = BillableFolderInsertOptions;
 export type ReplaceBillableFolderOptions = BillableFolderReplaceOptions;
@@ -34,31 +51,31 @@ export type SearchBillableFoldersOptions = OwnerSearchOptions;
 export type SearchBillableFoldersPage = SearchPage<BillableFolder>;
 export type CreateChargeOptions = ChargeInsertOptions;
 export type ReplaceChargeOptions = ChargeReplaceOptions;
-export type SearchChargesOptions = OwnerSearchOptions;
+export type SearchChargesOptions = OwnerSearchOptions & ChargeSearchFields;
 export type SearchChargesPage = SearchPage<Charge>;
 export type CreateEquipmentOptions = EquipmentInsertOptions;
 export type ReplaceEquipmentOptions = EquipmentReplaceOptions;
-export type SearchEquipmentsOptions = OwnerSearchOptions;
+export type SearchEquipmentsOptions = OwnerSearchOptions & EquipmentSearchFields;
 export type SearchEquipmentsPage = SearchPage<Equipment>;
 export type CreateItemOptions = ItemInsertOptions;
 export type ReplaceItemOptions = ItemReplaceOptions;
-export type SearchItemsOptions = OwnerSearchOptions;
+export type SearchItemsOptions = OwnerSearchOptions & ItemSearchFields;
 export type SearchItemsPage = SearchPage<Item>;
 export type CreateLaborRateOptions = LaborRateInsertOptions;
 export type ReplaceLaborRateOptions = LaborRateReplaceOptions;
-export type SearchLaborRatesOptions = OwnerSearchOptions;
+export type SearchLaborRatesOptions = OwnerSearchOptions & Partial<Pick<LaborRate, "is_archived">>;
 export type SearchLaborRatesPage = SearchPage<LaborRate>;
 export type CreateMeterReadingOptions = MeterReadingInsertOptions;
 export type ReplaceMeterReadingOptions = MeterReadingReplaceOptions;
-export type SearchMeterReadingsOptions = OwnerSearchOptions;
+export type SearchMeterReadingsOptions = OwnerSearchOptions & MeterReadingSearchFields;
 export type SearchMeterReadingsPage = SearchPage<MeterReading>;
 export type CreateQuantifierOptions = QuantifierInsertOptions;
 export type ReplaceQuantifierOptions = QuantifierReplaceOptions;
-export type SearchQuantifiersOptions = OwnerSearchOptions;
+export type SearchQuantifiersOptions = OwnerSearchOptions & Partial<Pick<Quantifier, "is_archived">>;
 export type SearchQuantifiersPage = SearchPage<Quantifier>;
 export type CreateTaxOptions = TaxInsertOptions;
 export type ReplaceTaxOptions = TaxReplaceOptions;
-export type SearchTaxesOptions = OwnerSearchOptions;
+export type SearchTaxesOptions = OwnerSearchOptions & Partial<Pick<Tax, "is_archived">>;
 export type SearchTaxesPage = SearchPage<Tax>;
 export type SearchAllTaxesOptions = Omit<SearchTaxesOptions, "page">;
 export type CreateTmpBillNumberOptions = TmpBillNumberInsertOptions;
@@ -70,11 +87,11 @@ export type CreateVendorInvoiceOptions = VendorInvoiceInsertOptions & {
     allow_duplicate?: boolean;
 };
 export type ReplaceVendorInvoiceOptions = VendorInvoiceReplaceOptions;
-export type SearchVendorInvoicesOptions = OwnerSearchOptions;
+export type SearchVendorInvoicesOptions = OwnerSearchOptions & Partial<Pick<VendorInvoice, "is_archived">>;
 export type SearchVendorInvoicesPage = SearchPage<VendorInvoice>;
 export type CreateWarehouseOptions = WarehouseInsertOptions;
 export type ReplaceWarehouseOptions = WarehouseReplaceOptions;
-export type SearchWarehousesOptions = OwnerSearchOptions;
+export type SearchWarehousesOptions = OwnerSearchOptions & Partial<Pick<Warehouse, "is_archived">>;
 export type SearchWarehousesPage = SearchPage<Warehouse>;
 export type BillableFXOptions = {
     billable: BillableOperator;
@@ -111,14 +128,12 @@ export type BillableReadSearchOptions = SearchOptions & {
     employer_scope_ids?: Iterable<string>;
     query?: SearchQuery;
 };
-export type BillableItemReadSearchOptions = BillableReadSearchOptions & {
-    warehouse_id?: string;
-    quantifier_id?: string;
-};
-export type BillableEquipmentReadSearchOptions = BillableReadSearchOptions & {
-    warehouse_id?: string;
-    rental_type?: string;
-};
+export type BillableItemReadSearchOptions = BillableReadSearchOptions & ItemSearchFields;
+export type BillableEquipmentReadSearchOptions = BillableReadSearchOptions & EquipmentSearchFields;
+export type BillableChargeReadSearchOptions = BillableReadSearchOptions & ChargeSearchFields;
+export type BillableMeterReadingReadSearchOptions = BillableReadSearchOptions & MeterReadingSearchFields;
+export type BillableQuantifierReadSearchOptions = BillableReadSearchOptions & Partial<Pick<Quantifier, "is_archived">>;
+export type BillableWarehouseReadSearchOptions = BillableReadSearchOptions & Partial<Pick<Warehouse, "is_archived">>;
 export type GenerateFixedEstimateOptions = {
     in: GenerateBillPayload;
 };
@@ -150,7 +165,7 @@ export interface BillableFXOperator {
     createCharge(opts: CreateChargeOptions): Promise<Charge>;
     replaceCharge(opts: ReplaceChargeOptions): Promise<Charge>;
     searchCharges(opts: SearchChargesOptions): Promise<SearchChargesPage>;
-    searchReadableCharges(opts: BillableReadSearchOptions): Promise<SearchChargesPage>;
+    searchReadableCharges(opts: BillableChargeReadSearchOptions): Promise<SearchChargesPage>;
     createEquipment(opts: CreateEquipmentOptions): Promise<Equipment>;
     replaceEquipment(opts: ReplaceEquipmentOptions): Promise<Equipment>;
     searchEquipments(opts: SearchEquipmentsOptions): Promise<SearchEquipmentsPage>;
@@ -165,11 +180,11 @@ export interface BillableFXOperator {
     createMeterReading(opts: CreateMeterReadingOptions): Promise<MeterReading>;
     replaceMeterReading(opts: ReplaceMeterReadingOptions): Promise<MeterReading>;
     searchMeterReadings(opts: SearchMeterReadingsOptions): Promise<SearchMeterReadingsPage>;
-    searchReadableMeterReadings(opts: BillableReadSearchOptions): Promise<SearchMeterReadingsPage>;
+    searchReadableMeterReadings(opts: BillableMeterReadingReadSearchOptions): Promise<SearchMeterReadingsPage>;
     createQuantifier(opts: CreateQuantifierOptions): Promise<Quantifier>;
     replaceQuantifier(opts: ReplaceQuantifierOptions): Promise<Quantifier>;
     searchQuantifiers(opts: SearchQuantifiersOptions): Promise<SearchQuantifiersPage>;
-    searchReadableQuantifiers(opts: BillableReadSearchOptions): Promise<SearchQuantifiersPage>;
+    searchReadableQuantifiers(opts: BillableQuantifierReadSearchOptions): Promise<SearchQuantifiersPage>;
     createTax(opts: CreateTaxOptions): Promise<Tax>;
     replaceTax(opts: ReplaceTaxOptions): Promise<Tax>;
     searchTaxes(opts: SearchTaxesOptions): Promise<SearchTaxesPage>;
@@ -183,7 +198,7 @@ export interface BillableFXOperator {
     createWarehouse(opts: CreateWarehouseOptions): Promise<Warehouse>;
     replaceWarehouse(opts: ReplaceWarehouseOptions): Promise<Warehouse>;
     searchWarehouses(opts: SearchWarehousesOptions): Promise<SearchWarehousesPage>;
-    searchReadableWarehouses(opts: BillableReadSearchOptions): Promise<SearchWarehousesPage>;
+    searchReadableWarehouses(opts: BillableWarehouseReadSearchOptions): Promise<SearchWarehousesPage>;
     generateFixedEstimate(opts: GenerateFixedEstimateOptions): Promise<Bill>;
     acceptFixedEstimate(opts: AcceptFixedEstimateOptions): Promise<Bill>;
     generateDynamicEstimate(opts: GenerateDynamicEstimateOptions): Promise<Bill>;
@@ -205,7 +220,7 @@ export declare class BillableFX implements BillableFXOperator {
     createCharge(opts: CreateChargeOptions): Promise<Charge>;
     replaceCharge(opts: ReplaceChargeOptions): Promise<Charge>;
     searchCharges(opts: SearchChargesOptions): Promise<SearchChargesPage>;
-    searchReadableCharges(opts: BillableReadSearchOptions): Promise<SearchChargesPage>;
+    searchReadableCharges(opts: BillableChargeReadSearchOptions): Promise<SearchChargesPage>;
     createEquipment(opts: CreateEquipmentOptions): Promise<Equipment>;
     replaceEquipment(opts: ReplaceEquipmentOptions): Promise<Equipment>;
     searchEquipments(opts: SearchEquipmentsOptions): Promise<SearchEquipmentsPage>;
@@ -220,11 +235,11 @@ export declare class BillableFX implements BillableFXOperator {
     createMeterReading(opts: CreateMeterReadingOptions): Promise<MeterReading>;
     replaceMeterReading(opts: ReplaceMeterReadingOptions): Promise<MeterReading>;
     searchMeterReadings(opts: SearchMeterReadingsOptions): Promise<SearchMeterReadingsPage>;
-    searchReadableMeterReadings(opts: BillableReadSearchOptions): Promise<SearchMeterReadingsPage>;
+    searchReadableMeterReadings(opts: BillableMeterReadingReadSearchOptions): Promise<SearchMeterReadingsPage>;
     createQuantifier(opts: CreateQuantifierOptions): Promise<Quantifier>;
     replaceQuantifier(opts: ReplaceQuantifierOptions): Promise<Quantifier>;
     searchQuantifiers(opts: SearchQuantifiersOptions): Promise<SearchQuantifiersPage>;
-    searchReadableQuantifiers(opts: BillableReadSearchOptions): Promise<SearchQuantifiersPage>;
+    searchReadableQuantifiers(opts: BillableQuantifierReadSearchOptions): Promise<SearchQuantifiersPage>;
     createTax(opts: CreateTaxOptions): Promise<Tax>;
     replaceTax(opts: ReplaceTaxOptions): Promise<Tax>;
     searchTaxes(opts: SearchTaxesOptions): Promise<SearchTaxesPage>;
@@ -238,7 +253,7 @@ export declare class BillableFX implements BillableFXOperator {
     createWarehouse(opts: CreateWarehouseOptions): Promise<Warehouse>;
     replaceWarehouse(opts: ReplaceWarehouseOptions): Promise<Warehouse>;
     searchWarehouses(opts: SearchWarehousesOptions): Promise<SearchWarehousesPage>;
-    searchReadableWarehouses(opts: BillableReadSearchOptions): Promise<SearchWarehousesPage>;
+    searchReadableWarehouses(opts: BillableWarehouseReadSearchOptions): Promise<SearchWarehousesPage>;
     generateFixedEstimate(opts: GenerateFixedEstimateOptions): Promise<Bill>;
     acceptFixedEstimate(opts: AcceptFixedEstimateOptions): Promise<Bill>;
     generateDynamicEstimate(opts: GenerateDynamicEstimateOptions): Promise<Bill>;
@@ -249,7 +264,6 @@ export declare class BillableFX implements BillableFXOperator {
     vendorInvoiceFromBill(opts: VendorInvoiceFromBillOptions): Promise<VendorInvoice>;
     private generateBill;
     private checkVendorInvoiceNumber;
-    private searchReadableActivity;
     private searchReadable;
     private findBill;
     private findBillableFolder;

package/dist/src/billable/billable.js

@@ -3,13 +3,13 @@
 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
-import { queryParams } from "@fabriktor/client";
+import { mergeQueryOptions, queryNestedParam, queryParams, } from "@fabriktor/client";
 import { BillTypeDynamic, BillTypeFixed, UserTypeEmployee, UserTypeEmployer, } from "@fabriktor/schema";
 import { isZeroDateTime } from "../core/date.js";
 import { errRequired, errResolveFailed, errValidation } from "../core/err.js";
 import { requiredOperationID, resolvedID } from "../core/id.js";
 import { runPreActionCheck } from "../core/pre-action.js";
-import { collectSearchResults, runOwnerScopeFilteredSearch, runOwnerScopeSearch, runOwnerSearch, withOwnerQuery, } from "../core/search.js";
+import { collectSearchResults, runOwnerScopeSearch, runOwnerSearch, withOwnerQuery, } from "../core/search.js";
 const resourceBill = "bill";
 const msgCreatedBillIDMissing = "Created bill response did not contain an ID.";
 const msgBillMissing = "Bill could not be resolved after the mutation.";
@@ -56,6 +56,26 @@ const msgBillIDRequired = "Bill ID is required.";
 const msgBillIDMissing = "Bill response did not contain an ID.";
 const msgCompletableBillRequired = "Only an uncanceled invoice can be completed.";
 const msgAcceptedEstimateCancellation = "Cancel the accepted invoice instead of its estimate.";
+// Composite sidebar states belong with their backend query mapping.
+export const BillFilter = {
+    All: "all",
+    NotCancelled: "not_cancelled",
+    Fixed: BillTypeFixed,
+    Dynamic: BillTypeDynamic,
+    Cancelled: "cancelled",
+};
+export function billFilterFields(value) {
+    switch (value) {
+        case BillFilter.All:
+            return {};
+        case BillFilter.NotCancelled:
+            return { is_canceled: false };
+        case BillFilter.Cancelled:
+            return { is_canceled: true };
+        default:
+            return { is_canceled: false, type: value };
+    }
+}
 export const BillableReadResource = {
     Bill: "bill",
     BillableFolder: "billable_folder",
@@ -114,6 +134,7 @@ export class BillableFX {
                 is_estimate: opts.is_estimate,
                 is_canceled: opts.is_canceled,
                 type: opts.type,
+                ...(opts.filter === undefined ? {} : billFilterFields(opts.filter)),
             }),
             search: (searchOpts) => this.billable.searchManyBills(searchOpts),
         });
@@ -145,12 +166,20 @@ export class BillableFX {
     async searchCharges(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: chargeSearchQuery(opts),
             search: (searchOpts) => this.billable.searchManyCharges(searchOpts),
         });
     }
     async searchReadableCharges(opts) {
-        return await this.searchReadableActivity({
+        const employer_ids = activityEmployerScopeIDs(opts);
+        return await this.searchReadable({
             ...opts,
+            // owner_id identifies the creator; employer_id identifies their employer.
+            // An explicitly empty authorized employer set must not become All.
+            allowed_owner_ids: employer_ids?.size === 0 ? [] : activityOwnerIDs(opts.context),
+            query: mergeQueryOptions(opts.query, chargeSearchQuery(opts), employer_ids === undefined ? undefined : queryParams({
+                employer_id: [...employer_ids],
+            })),
             search: (searchOpts) => this.billable.searchManyCharges(searchOpts),
         });
     }
@@ -166,18 +195,15 @@ export class BillableFX {
     async searchEquipments(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: equipmentSearchQuery(opts),
             search: (searchOpts) => this.billable.searchManyEquipments(searchOpts),
         });
     }
     async searchReadableEquipments(opts) {
-        const { warehouse_id, rental_type, ...search_opts } = opts;
         return await this.searchReadable({
-            ...search_opts,
+            ...opts,
+            query: mergeQueryOptions(opts.query, equipmentSearchQuery(opts)),
             allowed_owner_ids: catalogOwnerIDs(opts.context, opts.employer_scope_ids),
-            filter: warehouse_id === undefined && rental_type === undefined
-                ? undefined
-                : (equipment) => (warehouse_id === undefined || equipment.warehouse_id === warehouse_id) &&
-                    (rental_type === undefined || equipment.rental_type === rental_type),
             search: (searchOpts) => this.billable.searchManyEquipments(searchOpts),
         });
     }
@@ -193,19 +219,15 @@ export class BillableFX {
     async searchItems(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: itemSearchQuery(opts),
             search: (searchOpts) => this.billable.searchManyItems(searchOpts),
         });
     }
     async searchReadableItems(opts) {
-        const { warehouse_id, quantifier_id, ...search_opts } = opts;
         return await this.searchReadable({
-            ...search_opts,
+            ...opts,
+            query: mergeQueryOptions(opts.query, itemSearchQuery(opts)),
             allowed_owner_ids: catalogOwnerIDs(opts.context, opts.employer_scope_ids),
-            filter: warehouse_id === undefined && quantifier_id === undefined
-                ? undefined
-                : (item) => (warehouse_id === undefined ||
-                    item.per_warehouse_quantity.some((quantity) => quantity.warehouse_id === warehouse_id)) &&
-                    (quantifier_id === undefined || item.quantifier_id === quantifier_id),
             search: (searchOpts) => this.billable.searchManyItems(searchOpts),
         });
     }
@@ -221,6 +243,7 @@ export class BillableFX {
     async searchLaborRates(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: queryParams({ is_archived: opts.is_archived }),
             search: (searchOpts) => this.billable.searchManyLaborRates(searchOpts),
         });
     }
@@ -236,12 +259,19 @@ export class BillableFX {
     async searchMeterReadings(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: meterReadingSearchQuery(opts),
             search: (searchOpts) => this.billable.searchManyMeterReadings(searchOpts),
         });
     }
     async searchReadableMeterReadings(opts) {
-        return await this.searchReadableActivity({
+        const employer_ids = activityEmployerScopeIDs(opts);
+        return await this.searchReadable({
             ...opts,
+            // An explicitly empty authorized scope must stay empty, not become All.
+            allowed_owner_ids: employer_ids?.size === 0 ? [] : activityOwnerIDs(opts.context),
+            query: mergeQueryOptions(opts.query, meterReadingSearchQuery(opts), employer_ids === undefined ? undefined : queryParams({
+                employer_id: [...employer_ids],
+            })),
             search: (searchOpts) => this.billable.searchManyMeterReadings(searchOpts),
         });
     }
@@ -257,12 +287,16 @@ export class BillableFX {
     async searchQuantifiers(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: queryParams({ is_archived: opts.is_archived }),
             search: (searchOpts) => this.billable.searchManyQuantifiers(searchOpts),
         });
     }
     async searchReadableQuantifiers(opts) {
         return await this.searchReadable({
             ...opts,
+            query: mergeQueryOptions(opts.query, queryParams({
+                ...(opts.is_archived === undefined ? {} : { is_archived: opts.is_archived }),
+            })),
             allowed_owner_ids: catalogOwnerIDs(opts.context, opts.employer_scope_ids),
             search: (searchOpts) => this.billable.searchManyQuantifiers(searchOpts),
         });
@@ -279,6 +313,7 @@ export class BillableFX {
     async searchTaxes(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: queryParams({ is_archived: opts.is_archived }),
             search: (searchOpts) => this.billable.searchManyTaxes(searchOpts),
         });
     }
@@ -329,6 +364,7 @@ export class BillableFX {
     async searchVendorInvoices(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: queryParams({ is_archived: opts.is_archived }),
             search: (searchOpts) => this.billable.searchManyVendorInvoices(searchOpts),
         });
     }
@@ -344,12 +380,16 @@ export class BillableFX {
     async searchWarehouses(opts) {
         return await runOwnerSearch({
             ...opts,
+            query: queryParams({ is_archived: opts.is_archived }),
             search: (searchOpts) => this.billable.searchManyWarehouses(searchOpts),
         });
     }
     async searchReadableWarehouses(opts) {
         return await this.searchReadable({
             ...opts,
+            query: mergeQueryOptions(opts.query, queryParams({
+                ...(opts.is_archived === undefined ? {} : { is_archived: opts.is_archived }),
+            })),
             allowed_owner_ids: catalogOwnerIDs(opts.context, opts.employer_scope_ids),
             search: (searchOpts) => this.billable.searchManyWarehouses(searchOpts),
         });
@@ -424,38 +464,12 @@ export class BillableFX {
             },
         });
     }
-    async searchReadableActivity(opts) {
-        const employer_scope_ids = activityEmployerScopeIDs(opts);
-        return await this.searchReadable({
-            ...opts,
-            allowed_owner_ids: activityOwnerIDs(opts.context),
-            filter: employer_scope_ids === undefined
-                ? undefined
-                : (value) => employer_scope_ids.has(value.employer_id),
-        });
-    }
     async searchReadable(opts) {
-        const { context: _context, owner_ids: requested_owner_ids, employer_scope_ids: _employer_scope_ids, allowed_owner_ids, search, filter, query, ...searchOpts } = opts;
+        const { context: _context, owner_ids: requested_owner_ids, employer_scope_ids: _employer_scope_ids, allowed_owner_ids, search, query, ...searchOpts } = opts;
         const owner_ids = restrictOwnerIDs(allowed_owner_ids, requested_owner_ids);
-        const page = filter === undefined
-            ? await runOwnerScopeSearch({
-                ...searchOpts,
-                owner_ids,
-                query,
-                search,
-            })
-            : await runOwnerScopeFilteredSearch({
-                ...searchOpts,
-                owner_ids,
-                query,
-                search,
-                filter,
-                compare: compareCreatedAtDescending,
-            });
-        return {
-            ...page,
-            results: [...page.results].sort(compareCreatedAtDescending),
-        };
+        // Keep each backend page in its returned order. The owner contract requires
+        // separate requests; do not manufacture a cross-owner sort in the frontend.
+        return await runOwnerScopeSearch({ ...searchOpts, owner_ids, query, search });
     }
     async findBill(id) {
         const out = await this.billable.findOneBill({
@@ -712,6 +726,55 @@ function catalogOwnerIDs(context, employer_scope_ids) {
     }
     return uniqueIDs([context.owner_id]);
 }
+function itemSearchQuery(opts) {
+    return mergeQueryOptions(queryParams({
+        ...(opts.folder_id === undefined
+            ? {}
+            : { folder_id: resolvedID(opts.folder_id) }),
+        ...(opts.is_archived === undefined ? {} : { is_archived: opts.is_archived }),
+        ...(opts.quantifier_id === undefined
+            ? {}
+            : { quantifier_id: resolvedID(opts.quantifier_id) }),
+    }), opts.warehouse_id === undefined ? undefined : queryNestedParam(["per_warehouse_quantity", "warehouse_id"], resolvedID(opts.warehouse_id)));
+}
+function equipmentSearchQuery(opts) {
+    return queryParams({
+        ...(opts.folder_id === undefined
+            ? {}
+            : { folder_id: resolvedID(opts.folder_id) }),
+        ...(opts.is_archived === undefined ? {} : { is_archived: opts.is_archived }),
+        ...(opts.warehouse_id === undefined
+            ? {}
+            : { warehouse_id: resolvedID(opts.warehouse_id) }),
+        ...(opts.rental_type === undefined ? {} : { rental_type: opts.rental_type }),
+    });
+}
+function chargeSearchQuery(opts) {
+    return queryParams({
+        ...(opts.location_id === undefined
+            ? {}
+            : { location_id: resolvedID(opts.location_id) }),
+        ...(opts.entity_id === undefined
+            ? {}
+            : { entity_id: resolvedID(opts.entity_id) }),
+        ...(opts.warehouse_id === undefined
+            ? {}
+            : { warehouse_id: resolvedID(opts.warehouse_id) }),
+        ...(opts.type === undefined ? {} : { type: opts.type }),
+        ...(opts.is_estimate === undefined ? {} : { is_estimate: opts.is_estimate }),
+        ...(opts.is_billed === undefined ? {} : { is_billed: opts.is_billed }),
+    });
+}
+function meterReadingSearchQuery(opts) {
+    return queryParams({
+        ...(opts.location_id === undefined
+            ? {}
+            : { location_id: resolvedID(opts.location_id) }),
+        ...(opts.equipment_id === undefined
+            ? {}
+            : { equipment_id: resolvedID(opts.equipment_id) }),
+    });
+}
 function activityEmployerScopeIDs(opts) {
     if (opts.context.active_mode === UserTypeEmployer) {
         return new Set([opts.context.owner_id]);
@@ -739,13 +802,6 @@ function restrictOwnerIDs(allowed, requested) {
 function uniqueIDs(ids) {
     return [...new Set([...ids].map((id) => id.trim()).filter((id) => id !== ""))];
 }
-function compareCreatedAtDescending(left, right) {
-    return timestamp(right.created_at) - timestamp(left.created_at);
-}
-function timestamp(value) {
-    const out = globalThis.Date.parse(value);
-    return Number.isFinite(out) ? out : 0;
-}
 export function newBillableFX(opts) {
     return new BillableFX(opts);
 }

package/dist/src/core/search-controller.d.ts

@@ -0,0 +1,30 @@
+import { type SearchOptions, type SearchPage, type SearchResultWithID } from "./search.js";
+export type SearchState<T> = {
+    readonly results: readonly T[];
+    readonly ready: boolean;
+    readonly loading: boolean;
+    readonly loading_more: boolean;
+    readonly error: unknown;
+    readonly has_more: boolean;
+    readonly total_count?: number;
+};
+export type SearchControllerOptions<T, Options extends SearchOptions> = {
+    search: (opts: Options) => Promise<SearchPage<T>>;
+    on_change: (state: SearchState<T>) => void;
+};
+export declare class SearchController<T extends SearchResultWithID, Options extends SearchOptions> {
+    private readonly options;
+    private selection?;
+    private request?;
+    private next_page;
+    private current;
+    constructor(options: SearchControllerOptions<T, Options>);
+    get state(): SearchState<T>;
+    clear(): void;
+    replace(selection: Options): Promise<boolean>;
+    loadMore(): Promise<boolean>;
+    retry(): Promise<boolean>;
+    private load;
+    private emptyState;
+    private publish;
+}

package/dist/src/core/search-controller.js

@@ -0,0 +1,111 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+import { appendUniqueSearchResults, normalizeSearchPage, } from "./search.js";
+import { errUnknown } from "./err.js";
+// Holds only the current selection and its displayed pages. Previous queries
+// are discarded, and revisiting a selection always makes a backend request.
+export class SearchController {
+    options;
+    selection;
+    request;
+    next_page = normalizeSearchPage();
+    current = this.emptyState();
+    constructor(options) {
+        this.options = options;
+    }
+    get state() {
+        return this.current;
+    }
+    // Invalidate immediately, including during text-search debounce or teardown.
+    clear() {
+        this.request?.abort();
+        this.request = undefined;
+        this.selection = undefined;
+        this.next_page = normalizeSearchPage();
+        this.publish(this.emptyState());
+    }
+    async replace(selection) {
+        this.clear();
+        this.selection = { ...selection };
+        return await this.load(false);
+    }
+    async loadMore() {
+        if (!this.current.has_more || this.current.error !== undefined) {
+            return false;
+        }
+        return await this.load(true);
+    }
+    async retry() {
+        return await this.load(this.next_page > normalizeSearchPage());
+    }
+    async load(append) {
+        if (!this.selection || this.current.loading || this.current.loading_more) {
+            return false;
+        }
+        const request = new AbortController();
+        this.request = request;
+        this.publish({
+            ...this.current,
+            loading: !append,
+            loading_more: append,
+            error: undefined,
+        });
+        try {
+            const page = await this.options.search({
+                ...this.selection,
+                page: this.next_page,
+                signal: request.signal,
+            });
+            if (this.request !== request || request.signal.aborted) {
+                return false;
+            }
+            this.next_page = page.next_page;
+            this.publish({
+                results: append
+                    ? appendUniqueSearchResults(this.current.results, page.results)
+                    : page.results,
+                ready: true,
+                loading: false,
+                loading_more: false,
+                error: undefined,
+                has_more: page.has_more,
+                total_count: page.total_count,
+            });
+            return true;
+        }
+        catch (error) {
+            if (this.request !== request || request.signal.aborted) {
+                return false;
+            }
+            this.publish({
+                ...this.current,
+                loading: false,
+                loading_more: false,
+                error: errUnknown(error),
+            });
+            return false;
+        }
+        finally {
+            if (this.request === request) {
+                this.request = undefined;
+            }
+        }
+    }
+    emptyState() {
+        return {
+            results: [],
+            ready: false,
+            loading: false,
+            loading_more: false,
+            error: undefined,
+            has_more: false,
+        };
+    }
+    publish(state) {
+        this.current = state;
+        this.options.on_change(state);
+    }
+}

package/dist/src/core/search.d.ts

@@ -4,7 +4,7 @@ export type SearchPaginationOptions = {
     page?: number;
     per_page?: number;
 };
-export type SearchOptions = SearchPaginationOptions & {
+export type SearchOptions = SearchPaginationOptions & Pick<SearchManyOptionsCRUD, "signal"> & {
     q?: string;
 };
 export type RequiredSearchOptions = SearchPaginationOptions & {
@@ -54,3 +54,7 @@ export declare function runSearch<T>(opts: RunSearchOptions<T>): Promise<SearchP
 export declare function normalizeSearchPage(value?: number): number;
 export declare function normalizeSearchPerPage(value?: number): number;
 export declare function normalizeSearchQuery(value?: string): string | undefined;
+export type SearchResultWithID = {
+    readonly id: string;
+};
+export declare function appendUniqueSearchResults<T extends SearchResultWithID>(current: readonly T[], next: readonly T[]): T[];

package/dist/src/core/search.js

@@ -48,6 +48,7 @@ export async function runOwnerScopeSearch(opts) {
         per_page,
         query: opts.query,
         search: opts.search,
+        signal: opts.signal,
     })));
     const results = new Map();
     for (const ownerPage of pages) {
@@ -94,6 +95,7 @@ export async function runOwnerScopeFilteredSearch(opts) {
                 per_page,
                 query: opts.query,
                 search: opts.search,
+                signal: opts.signal,
             }),
         })));
         for (const owner_page of pages) {
@@ -147,6 +149,7 @@ export async function runSearch(opts) {
         };
     const raw = await opts.search({
         query,
+        signal: opts.signal,
     });
     return resolveSearchPage({
         raw,
@@ -236,3 +239,17 @@ function maxDefined(values) {
     }
     return Math.max(...values.map((value) => value ?? 0));
 }
+export function appendUniqueSearchResults(current, next) {
+    const out = [...current];
+    const indexes = new Map(out.map((item, index) => [item.id, index]));
+    for (const item of next) {
+        const index = indexes.get(item.id);
+        if (index === undefined) {
+            indexes.set(item.id, out.length);
+            out.push(item);
+            continue;
+        }
+        out[index] = item;
+    }
+    return out;
+}

package/dist/src/index.d.ts

@@ -12,6 +12,7 @@ export * from "./core/pre-action.js";
 export * from "./core/pull.js";
 export * from "./core/queue-store.js";
 export * from "./core/queue.js";
+export * from "./core/search-controller.js";
 export * from "./core/search.js";
 export * from "./feed/feed.js";
 export * from "./fulfillments/fulfillments.js";

package/dist/src/index.js

@@ -12,6 +12,7 @@ export * from "./core/pre-action.js";
 export * from "./core/pull.js";
 export * from "./core/queue-store.js";
 export * from "./core/queue.js";
+export * from "./core/search-controller.js";
 export * from "./core/search.js";
 export * from "./feed/feed.js";
 export * from "./fulfillments/fulfillments.js";

package/dist/src/memos/memos.d.ts

@@ -1,5 +1,5 @@
-import type { MemosOperator } from "@fabriktor/client";
-import type { Memo, MemoFolder } from "@fabriktor/schema";
+import { type MemosOperator } from "@fabriktor/client";
+import { type Memo, type MemoFolder } from "@fabriktor/schema";
 import { type OwnerSearchOptions, type SearchPage } from "../core/search.js";
 type MemoInsertOptions = Parameters<MemosOperator["insertOneMemo"]>[0];
 type MemoReplaceOptions = Parameters<MemosOperator["replaceOneMemo"]>[0];
@@ -9,7 +9,7 @@ export type CreateMemoOptions = MemoInsertOptions;
 export type ReplaceMemoOptions = MemoReplaceOptions;
 export type CreateMemoFolderOptions = MemoFolderInsertOptions;
 export type ReplaceMemoFolderOptions = MemoFolderReplaceOptions;
-export type SearchMemosOptions = OwnerSearchOptions;
+export type SearchMemosOptions = OwnerSearchOptions & Partial<Pick<Memo, "is_archived" | "folder_id">>;
 export type SearchMemoFoldersOptions = OwnerSearchOptions;
 export type SearchMemosPage = SearchPage<Memo>;
 export type SearchMemoFoldersPage = SearchPage<MemoFolder>;

package/dist/src/memos/memos.js

@@ -3,13 +3,16 @@
 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
-import { errResolveFailed } from "../core/err.js";
-import { requiredOperationID } from "../core/id.js";
+import { queryParams } from "@fabriktor/client";
+import { OwnerIDKey } from "@fabriktor/schema";
+import { errRequired, errResolveFailed } from "../core/err.js";
+import { requiredOperationID, resolvedID } from "../core/id.js";
 import { runOwnerSearch, } from "../core/search.js";
 const resourceMemo = "memo";
 const resourceMemoFolder = "memo_folder";
 const msgCreatedMemoIDMissing = "Created memo response did not contain an ID.";
 const msgMemoMissing = "Memo could not be resolved after the mutation.";
+const msgMemoOwnerRequired = "Memo owner is required.";
 const msgCreatedMemoFolderIDMissing = "Created memo folder response did not contain an ID.";
 const msgMemoFolderMissing = "Memo folder could not be resolved after the mutation.";
 export class MemosFX {
@@ -36,8 +39,18 @@ export class MemosFX {
         return await this.findMemoFolder(opts.id);
     }
     async searchMemos(opts) {
+        const { is_archived, folder_id, ...searchOpts } = opts;
+        const owner_id = resolvedID(opts.owner_id);
+        if (owner_id === undefined) {
+            throw errRequired({ field: OwnerIDKey, msg: msgMemoOwnerRequired });
+        }
         return await runOwnerSearch({
-            ...opts,
+            ...searchOpts,
+            owner_id,
+            query: queryParams({
+                is_archived,
+                folder_id: resolvedID(folder_id),
+            }),
             search: (searchOpts) => this.memos.searchManyMemos(searchOpts),
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.105",
+  "version": "0.0.106",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@fabriktor/client": "0.0.82",
+    "@fabriktor/client": "0.0.83",
     "@fabriktor/fx": "0.0.94",
     "@fabriktor/schema": "0.0.63"
   }