contracts — Functions

Functions and classes for the contracts package

Functions and classes exported by this package.

isValidStatus()

Signature

(entityType: EntityType, value: string) => boolean

SessionView

SessionView — typed wrapper over Session[] with collection helpers. Provides discoverable query methods for common session lookups. Does NOT change the DataAccessor interface — consumers create views from Session[].

Signature

typeof SessionView

Methods

from()

Create a SessionView from a Session array.

(sessions: Session[]) => SessionView

findActive()

Find the currently active session (if any).

() => Session | undefined

findById()

Find a session by ID.

(id: string) => Session | undefined

filterByStatus()

Filter sessions by one or more statuses.

(...statuses: SessionStatus[]) => Session[]

findByScope()

Find sessions matching a scope type and optional rootTaskId.

(type: string, rootTaskId?: string) => Session[]

sortByDate()

Sort sessions by a date field. Returns a new array (does not mutate).

(field: "startedAt" | "endedAt", descending?: boolean) => Session[]

mostRecent()

Get the most recently started session.

() => Session | undefined

toArray()

Convert back to a plain Session array (shallow copy).

() => Session[]

[Symbol.iterator]()

Support for-of iteration.

() => Iterator<Session>

normalizeError(error, fallbackMessage)

Normalize any thrown value into a standardized error object. Handles: - Error instances (preserves stack trace info) - Strings (wraps in Error) - Objects with message property - null/undefined (provides fallback)

Signature

(error: unknown, fallbackMessage?: string) => Error

Parameters

Name	Type	Description
error	unknown	The thrown value to normalize
fallbackMessage	: string	Message to use if error provides none

Returns — Normalized error with consistent shape

Example

try {
  await riskyOperation();
} catch (err) {
  const error = normalizeError(err, 'Operation failed');
  console.error(error.message);
}

getErrorMessage(error, fallback)

Extract a human-readable message from any error value. Safe to use on unknown thrown values without type guards.

Signature

(error: unknown, fallback?: string) => string

Parameters

Name	Type	Description
error	unknown	The error value
fallback	: string	Fallback message if extraction fails

Returns — The error message string

Example

const message = getErrorMessage(err, 'Unknown error');

formatError(error, context, includeStack)

Format error details for logging or display. Includes stack trace for Error instances when includeStack is true.

Signature

(error: unknown, context?: string, includeStack?: boolean) => string

Parameters

Name	Type	Description
error	unknown	The error to format
context	: string	Optional context to prepend
includeStack	: boolean	Whether to include stack traces (default: false)

Returns — Formatted error string

Example

console.error(formatError(err, 'Database connection'));
// Output: [Database connection] Connection refused

isErrorType(error, codeOrName)

Check if an error represents a specific error type by code or name. Useful for conditional error handling based on error types.

Signature

(error: unknown, codeOrName: string) => boolean

Parameters

Name	Type	Description
error	unknown	The error to check
codeOrName	string	The error code or name to match

Returns — True if the error matches

Example

if (isErrorType(err, 'E_NOT_FOUND')) {
  // Handle not found specifically
}

createErrorResult(error)

Create a standardized error result object. Common pattern for operations that return success: boolean, error?: string

Signature

(error: unknown) => { success: false; error: string; }

Parameters

Name	Type	Description
error	unknown	The error value

Returns — Error result object

Example

return createErrorResult(err);
// Returns: { success: false, error: "Something went wrong" }

createSuccessResult()

Create a standardized success result object.

Signature

() => { success: true; }

Returns — Success result object

Example

return createSuccessResult();
// Returns: { success: true }

isErrorResult(result)

Type guard for error results.

Signature

(result: { success: boolean; error?: string; }) => result is { success: false; error: string; }

Parameters

Name	Type	Description
result	{ success: boolean; error?: string; }	The result to check

Returns — True if the result is an error result

Example

const result = await someOperation();
if (isErrorResult(result)) {
  console.error(result.error);
}

isErrorCode()

Check if an exit code represents an error (1-99).

Signature

(code: ExitCode) => boolean

isSuccessCode()

Check if an exit code represents success (0 or 100+).

Signature

(code: ExitCode) => boolean

isNoChangeCode()

Check if an exit code indicates no change (idempotent operation).

Signature

(code: ExitCode) => boolean

isRecoverableCode()

Check if an exit code is recoverable (retry may succeed).

Signature

(code: ExitCode) => boolean

getExitCodeName()

Human-readable name for an exit code.

Signature

(code: ExitCode) => string

isLafsSuccess(envelope)

Type guard for success responses.

Signature

<T>(envelope: LafsEnvelope<T>) => envelope is LafsSuccess<T>

Parameters

Name	Type	Description
envelope	LafsEnvelope<T>	The envelope to check.

Returns — true if the envelope represents a successful operation.

Example

const result: LafsEnvelope<Task[]> = await fetchTasks();
if (isLafsSuccess(result)) {
  console.log(result.data); // Task[]
}

isLafsError(envelope)

Type guard for error responses.

Signature

<T>(envelope: LafsEnvelope<T>) => envelope is LafsError

Parameters

Name	Type	Description
envelope	LafsEnvelope<T>	The envelope to check.

Returns — true if the envelope represents a failed operation.

Example

const result: LafsEnvelope<Task[]> = await fetchTasks();
if (isLafsError(result)) {
  console.error(result.error.message);
}

isGatewayEnvelope(envelope)

Type guard for gateway responses (has _meta).

Signature

<T>(envelope: CleoResponse<T>) => envelope is GatewayEnvelope<T>

Parameters

Name	Type	Description
envelope	CleoResponse<T>	The response to check.

Returns — true if the response includes gateway metadata.

Example

const response: CleoResponse<Task> = await handleRequest();
if (isGatewayEnvelope(response)) {
  console.log(response._meta.gateway);
}