import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
import type { DtoField } from './dto.js';
import type { ExceptionSchema } from './exception.js';
import type { FrontAppSchema, ProjectApiSchema } from './project.js';
/** A utility method with a full signature. */
export interface UtilsMethodSchema extends SchemaBase {
    type: 'utilsMethod';
    /** The utility module this method belongs to. */
    schema: UtilsSchema;
    /** Input fields — DtoField wrappers (dtoField(...)); may wrap table columns. */
    args: Record<string, DtoField>;
    /** Output field — a plain inline Field (boolean for checks, decimal for
     *  computed amounts, ...). The method output is a fresh value, never a
     *  shared table column. Omit for void methods (pure actions). */
    result?: Field;
    /** Exceptions this method may throw — the failure contract of a defense
     *  guard (assert/validate/ensure: void, throws internally). Flows route
     *  invoked guards' throws into their escape set automatically, so a
     *  guard's throws must be declared by the calling service method (or
     *  caught in a TRY). Predicates (can/is/has, boolean) do not throw. */
    throws?: ExceptionSchema[];
}
/** Method input for defineUtils: type/schema/name are set by the builder. */
export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>;
/** A base utility module (e.g. DateTimeUtils). */
export interface UtilsSchema extends CollectionSchemaBase {
    type: 'utils';
    /** Backend binding — the api module this utils belongs to (shared instance
     *  from project.config.ts apis). With `app` it serves that frontend
     *  ({api}/{app}/utils/); alone it is the api's public module
     *  ({api}/common/utils/). Unset = not backend-side. */
    api?: ProjectApiSchema;
    /** Optional binding — the frontend app this utils serves (shared instance
     *  from project.config.ts apps). Empty means a shared public module. */
    app?: FrontAppSchema;
    /** Methods keyed by name — the map key is written back as the method name. */
    methods: Record<string, UtilsMethodSchema>;
}
export declare function defineUtils(options: {
    name: string;
    api?: ProjectApiSchema;
    app?: FrontAppSchema;
    methods: Record<string, UtilsMethodDef>;
    description?: string;
}): UtilsSchema;