@saptools/service-flow 0.1.51 → 0.1.53

package/src/trace/001-dynamic-identity.ts

@@ -0,0 +1,308 @@
+import type { Db } from '../db/connection.js';
+import type {
+  DynamicTargetCandidate,
+  DynamicTemplates,
+  DynamicVariableProvenance,
+} from './000-dynamic-target-types.js';
+
+interface RouteImplementationEvidence {
+  routeRepoId?: number;
+  handlerRepo?: string;
+  operationProvenance?: string;
+  baseOperationId?: number;
+  edgeStatus?: string;
+}
+
+interface IdentityProposal {
+  operationId: number;
+  key: string;
+  value: string;
+  normalizedIdentity: string;
+  provenance: DynamicVariableProvenance;
+}
+
+interface RepositoryIdentity {
+  repoId: number;
+  repoName: string;
+  packageName?: string;
+}
+
+interface WorkspaceIdentityMatch {
+  ownerKey: string;
+  key: string;
+  value: string;
+  normalizedIdentity: string;
+}
+
+export interface IdentityDerivation {
+  operationId: number;
+  key: string;
+  value: string;
+  provenance: DynamicVariableProvenance;
+}
+
+export function uniqueIdentityDerivations(
+  db: Db,
+  candidates: DynamicTargetCandidate[],
+  templates: DynamicTemplates,
+): IdentityDerivation[] {
+  const identities = workspaceIdentities(db, candidates);
+  const proposals = candidates.flatMap((candidate) => {
+    const implementation = routeImplementationEvidence(
+      db, candidate.candidateOperationId,
+    );
+    const identity = identities.find((item) => item.repoId === candidate.repoId);
+    if (!identity || !implementation || !routeOwnerAgrees(candidate, implementation))
+      return [];
+    return identityProposals(candidate, identity, templates, implementation);
+  });
+  const matches = workspaceIdentityMatches(identities, templates);
+  const competing = competingIdentityKeys(matches);
+  const duplicates = duplicateNormalizedIdentities(identities);
+  return proposals
+    .filter((proposal) => !competing.has(`${proposal.key}:${proposal.value}`))
+    .filter((proposal) => !duplicates.has(proposal.normalizedIdentity))
+    .map((proposal) => ({
+      operationId: proposal.operationId,
+      key: proposal.key,
+      value: proposal.value,
+      provenance: proposal.provenance,
+    }));
+}
+
+function identityProposals(
+  candidate: DynamicTargetCandidate,
+  identity: RepositoryIdentity,
+  templates: DynamicTemplates,
+  implementation: RouteImplementationEvidence,
+): IdentityProposal[] {
+  const routeTemplates = [templates.alias, templates.destination]
+    .filter((value): value is string => Boolean(value));
+  const identities = [
+    { name: identity.packageName, sourceKind: 'package_identity', npmPackage: true },
+    { name: identity.repoName, sourceKind: 'repository_identity', npmPackage: false },
+  ].filter((item): item is {
+    name: string; sourceKind: string; npmPackage: boolean;
+  } => Boolean(item.name));
+  const proposals = routeTemplates.flatMap((template) =>
+    identities.flatMap((identity) =>
+      proposalForIdentity(
+        candidate, template, identity.name, identity.sourceKind,
+        identity.npmPackage, implementation,
+      )));
+  return deduplicateProposals(proposals);
+}
+
+function proposalForIdentity(
+  candidate: DynamicTargetCandidate,
+  template: string,
+  identity: string,
+  sourceKind: string,
+  npmPackage: boolean,
+  implementation: RouteImplementationEvidence,
+): IdentityProposal[] {
+  const match = matchIdentityTemplate(template, identity, npmPackage);
+  if (!match) return [];
+  return [{
+    operationId: candidate.candidateOperationId,
+    key: match.key,
+    value: match.value,
+    normalizedIdentity: match.normalizedIdentity,
+    provenance: {
+      sourceKind,
+      value: match.value,
+      rule: 'exact_normalized_identity_template_match',
+      template,
+      matchedName: identity,
+      normalizedForm: match.normalizedIdentity,
+      sourceRepo: candidate.repoName,
+      routeOwner: candidate.repoName,
+      candidateOperationId: candidate.candidateOperationId,
+      effectiveBaseOperationId: implementation.baseOperationId,
+      candidateOperationProvenance: implementation.operationProvenance,
+      implementationEdgeStatus: implementation.edgeStatus,
+      implementationHandlerRepo: implementation.handlerRepo,
+    },
+  }];
+}
+
+function matchIdentityTemplate(
+  template: string,
+  identity: string,
+  npmPackage: boolean,
+): { key: string; value: string; normalizedIdentity: string } | undefined {
+  const matches = [...template.matchAll(/\$\{([^}]*)\}/g)];
+  if (matches.length !== 1 || !matches[0]?.[1]) return undefined;
+  const placeholder = matches[0][0];
+  const sentinel = 'dynamicplaceholdertoken';
+  const normalizedTemplate = normalizeIdentity(template.replace(placeholder, sentinel));
+  const [prefix, suffix, extra] = normalizedTemplate.split(sentinel);
+  if (!prefix || !suffix || extra !== undefined) return undefined;
+  const normalizedIdentity = normalizeIdentity(identity, npmPackage);
+  const match = new RegExp(`^${escapeRegex(prefix)}([a-z0-9]+)${escapeRegex(suffix)}$`)
+    .exec(normalizedIdentity);
+  if (!match?.[1]) return undefined;
+  return { key: matches[0][1].trim(), value: match[1], normalizedIdentity };
+}
+
+function competingIdentityKeys(
+  proposals: Array<{ key: string; value: string; ownerKey: string }>,
+): Set<string> {
+  const owners = new Map<string, Set<string>>();
+  for (const proposal of proposals) {
+    const key = `${proposal.key}:${proposal.value}`;
+    owners.set(key, new Set([...(owners.get(key) ?? []), proposal.ownerKey]));
+  }
+  return new Set([...owners.entries()]
+    .filter(([, repos]) => repos.size > 1)
+    .map(([key]) => key));
+}
+
+function duplicateNormalizedIdentities(
+  identities: RepositoryIdentity[],
+): Set<string> {
+  const owners = new Map<string, Set<string>>();
+  for (const identity of identities) {
+    for (const [name, npmPackage] of [
+      [identity.packageName, true],
+      [identity.repoName, false],
+    ] as const) {
+      if (!name) continue;
+      const normalized = normalizeIdentity(name, npmPackage);
+      owners.set(normalized, new Set([
+        ...(owners.get(normalized) ?? []),
+        `repository:${identity.repoId}`,
+      ]));
+    }
+  }
+  return new Set([...owners.entries()]
+    .filter(([, repos]) => repos.size > 1)
+    .map(([identity]) => identity));
+}
+
+function workspaceIdentityMatches(
+  identities: RepositoryIdentity[],
+  templates: DynamicTemplates,
+): WorkspaceIdentityMatch[] {
+  const routeTemplates = [templates.alias, templates.destination]
+    .filter((value): value is string => Boolean(value));
+  return identities.flatMap((identity) => {
+    const names: Array<{ name?: string; npmPackage: boolean }> = [
+      { name: identity.packageName, npmPackage: true },
+      { name: identity.repoName, npmPackage: false },
+    ];
+    return routeTemplates.flatMap((template) =>
+      names.flatMap(({ name, npmPackage }) => {
+        if (!name) return [];
+        const match = matchIdentityTemplate(template, name, npmPackage);
+        return match ? [{
+          ownerKey: `repository:${identity.repoId}`,
+          key: match.key,
+          value: match.value,
+          normalizedIdentity: match.normalizedIdentity,
+        }] : [];
+      }));
+  });
+}
+
+function workspaceIdentities(
+  db: Db,
+  candidates: DynamicTargetCandidate[],
+): RepositoryIdentity[] {
+  const repoIds = [...new Set(candidates.flatMap((candidate) =>
+    candidate.repoId === undefined ? [] : [candidate.repoId]))].sort((a, b) => a - b);
+  if (repoIds.length === 0) return [];
+  const placeholders = repoIds.map(() => '?').join(',');
+  const rows = db.prepare(`SELECT id repoId,name repoName,package_name packageName
+    FROM repositories WHERE workspace_id IN (
+      SELECT DISTINCT workspace_id FROM repositories WHERE id IN (${placeholders})
+    ) ORDER BY workspace_id,name,absolute_path,id`).all(...repoIds);
+  return rows.flatMap((row): RepositoryIdentity[] => {
+    const repoId = numberValue(row.repoId);
+    const repoName = stringValue(row.repoName);
+    return repoId === undefined || !repoName ? [] : [{
+      repoId,
+      repoName,
+      packageName: stringValue(row.packageName),
+    }];
+  });
+}
+
+function deduplicateProposals(rows: IdentityProposal[]): IdentityProposal[] {
+  const sorted = [...rows].sort((left, right) =>
+    left.operationId - right.operationId
+    || left.key.localeCompare(right.key)
+    || left.value.localeCompare(right.value)
+    || left.provenance.sourceKind.localeCompare(right.provenance.sourceKind));
+  const seen = new Set<string>();
+  return sorted.filter((row) => {
+    const key = [row.operationId, row.key, row.value, row.normalizedIdentity].join(':');
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function routeOwnerAgrees(
+  candidate: DynamicTargetCandidate,
+  implementation: RouteImplementationEvidence | undefined,
+): boolean {
+  return candidate.repoId !== undefined
+    && implementation?.routeRepoId === candidate.repoId
+    && implementation.edgeStatus === 'resolved'
+    && candidate.viable
+    && candidate.reasons.includes('service_path_template_match');
+}
+
+function routeImplementationEvidence(
+  db: Db,
+  operationId: number,
+): RouteImplementationEvidence | undefined {
+  const rows = db.prepare(
+    `SELECT s.repo_id routeRepoId,o.provenance operationProvenance,
+      o.base_operation_id baseOperationId,e.status edgeStatus,
+      r.name handlerRepo
+     FROM cds_operations o JOIN cds_services s ON s.id=o.service_id
+     JOIN graph_edges e ON e.edge_type='OPERATION_IMPLEMENTED_BY_HANDLER'
+       AND e.from_kind='operation' AND e.from_id=CAST(o.id AS TEXT)
+     JOIN handler_methods hm ON hm.id=CAST(e.to_id AS INTEGER)
+     JOIN handler_classes hc ON hc.id=hm.handler_class_id
+     JOIN repositories r ON r.id=hc.repo_id
+     WHERE e.edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND e.status='resolved'
+       AND o.id=?
+     ORDER BY e.id,hm.id`,
+  ).all(String(operationId));
+  if (rows.length !== 1) return undefined;
+  const row = rows[0];
+  if (!row) return undefined;
+  return {
+    routeRepoId: numberValue(row.routeRepoId),
+    handlerRepo: stringValue(row.handlerRepo),
+    operationProvenance: stringValue(row.operationProvenance),
+    baseOperationId: numberValue(row.baseOperationId),
+    edgeStatus: stringValue(row.edgeStatus),
+  };
+}
+
+function normalizeIdentity(value: string, npmPackage = false): string {
+  const unscoped = npmPackage && /^@[^/]+\/[^/]+$/.test(value)
+    ? value.slice(value.indexOf('/') + 1)
+    : value;
+  return unscoped
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/trace/002-trace-diagnostics.ts

@@ -0,0 +1,54 @@
+import type { Db } from '../db/connection.js';
+
+export function loadTraceDiagnostics(
+  db: Db,
+  repoId: number | undefined,
+  includeWorkspaceDiagnostics: boolean,
+  workspaceId?: number,
+): Array<Record<string, unknown>> {
+  if (repoId === undefined && !includeWorkspaceDiagnostics) return [];
+  return db.prepare(`SELECT d.repo_id repoId,d.severity,d.code,d.message,
+      d.source_file sourceFile,d.source_line sourceLine
+    FROM diagnostics d LEFT JOIN repositories r ON r.id=d.repo_id
+    WHERE (? IS NULL OR d.repo_id=?)
+      AND (? IS NULL OR d.repo_id IS NULL OR r.workspace_id=?)
+    ORDER BY severity,code,COALESCE(source_file,''),
+      COALESCE(source_line,0),d.id`).all(
+        repoId, repoId, workspaceId, workspaceId,
+      ) as Array<
+        Record<string, unknown>
+      >;
+}
+
+export function prependTraceDiagnostic(
+  diagnostics: Array<Record<string, unknown>>,
+  diagnostic: Record<string, unknown>,
+): void {
+  const duplicate = diagnostics.findIndex((item) =>
+    sameDiagnosticLocation(item, diagnostic));
+  if (duplicate >= 0) diagnostics.splice(duplicate, 1);
+  diagnostics.unshift(diagnostic);
+}
+
+function sameDiagnosticLocation(
+  left: Record<string, unknown>,
+  right: Record<string, unknown>,
+): boolean {
+  if (left.code !== right.code) return false;
+  const leftFile = stringValue(left.sourceFile);
+  const rightFile = stringValue(right.sourceFile);
+  if (leftFile || rightFile)
+    return leftFile === rightFile
+      && numericValue(left.sourceLine) === numericValue(right.sourceLine);
+  return String(left.message ?? '') === String(right.message ?? '');
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function numericValue(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? value
+    : undefined;
+}

package/src/trace/003-dynamic-references.ts

@@ -0,0 +1,283 @@
+import type { Db } from '../db/connection.js';
+import {
+  projectBounded,
+  type BoundedProjection,
+} from '../utils/000-bounded-projection.js';
+import type { DynamicVariableProvenance } from './000-dynamic-target-types.js';
+
+export interface DynamicReferenceRow {
+  bindingId?: number;
+  alias?: string;
+  aliasExpr?: string;
+  destination?: string;
+  servicePath?: string;
+  sourceKind: 'service_binding' | 'cds_require';
+  selection: 'selected_binding' | 'selected_binding_require' | 'fallback';
+  repoName: string;
+  sourceFile?: string;
+  sourceLine?: number;
+  helperChain?: unknown;
+}
+
+export interface DynamicRoutingContext {
+  outboundCallId?: number;
+  callerRepoId?: number;
+  callerRepo?: string;
+  selectedBindingId?: number;
+  bindingResolutionStatus: string;
+  selectedBinding?: DynamicReferenceRow;
+  bindingAlternatives: Array<Record<string, unknown>>;
+  bindingAlternativeCount: number;
+  shownBindingAlternativeCount: number;
+  omittedBindingAlternativeCount: number;
+  references: DynamicReferenceRow[];
+  fallbackUsed: boolean;
+}
+
+interface SelectedDynamicReference extends DynamicReferenceRow {
+  outboundCallId: number;
+  callerRepoId: number;
+}
+
+export function dynamicRoutingContext(
+  db: Db,
+  workspaceId: number | undefined,
+  evidence: Record<string, unknown>,
+): DynamicRoutingContext {
+  const selected = selectedBinding(db, workspaceId, evidence);
+  const persisted = persistedBindingResolution(evidence);
+  const alternatives = boundedAlternatives(
+    persisted.candidates,
+    persisted.candidateCount,
+  );
+  if (selected) {
+    const requires = exactRequireReferences(db, workspaceId, selected);
+    return {
+      ...contextBase(selected, persisted.status, alternatives),
+      selectedBinding: selected,
+      references: [selected, ...requires],
+      fallbackUsed: false,
+    };
+  }
+  const callerRepoId = numberValue(evidence.repoId);
+  const callerRepo = stringValue(evidence.repo);
+  return {
+    outboundCallId: numberValue(evidence.outboundCallId ?? evidence.callId),
+    callerRepoId,
+    callerRepo,
+    bindingResolutionStatus: persisted.status,
+    bindingAlternatives: alternatives.items,
+    bindingAlternativeCount: alternatives.totalCount,
+    shownBindingAlternativeCount: alternatives.shownCount,
+    omittedBindingAlternativeCount: alternatives.omittedCount,
+    references: fallbackReferences(db, workspaceId, callerRepoId, callerRepo),
+    fallbackUsed: true,
+  };
+}
+
+export function dynamicReferenceProvenance(
+  reference: DynamicReferenceRow,
+  kind: 'alias' | 'destination',
+  template: string,
+  value: string,
+): DynamicVariableProvenance {
+  const sourceKind = reference.selection === 'selected_binding'
+    ? `selected_binding.${kind}`
+    : reference.selection === 'selected_binding_require'
+      ? `selected_binding_require.${kind}`
+      : `${reference.sourceKind}.${kind}`;
+  return {
+    sourceKind,
+    value,
+    rule: 'exact_indexed_reference_template_match',
+    template,
+    sourceRepo: reference.repoName,
+    sourceFile: reference.sourceFile,
+    sourceLine: reference.sourceLine,
+    selection: reference.selection,
+    bindingId: reference.bindingId,
+  };
+}
+
+function contextBase(
+  selected: SelectedDynamicReference,
+  status: string,
+  alternatives: ReturnType<typeof boundedAlternatives>,
+): Omit<DynamicRoutingContext, 'selectedBinding' | 'references' | 'fallbackUsed'> {
+  return {
+    outboundCallId: selected.outboundCallId,
+    callerRepoId: selected.callerRepoId,
+    callerRepo: selected.repoName,
+    selectedBindingId: selected.bindingId,
+    bindingResolutionStatus: status,
+    bindingAlternatives: alternatives.items,
+    bindingAlternativeCount: alternatives.totalCount,
+    shownBindingAlternativeCount: alternatives.shownCount,
+    omittedBindingAlternativeCount: alternatives.omittedCount,
+  };
+}
+
+function selectedBinding(
+  db: Db,
+  workspaceId: number | undefined,
+  evidence: Record<string, unknown>,
+): SelectedDynamicReference | undefined {
+  const callId = numberValue(evidence.outboundCallId ?? evidence.callId);
+  if (callId === undefined) return undefined;
+  const row = db.prepare(`SELECT c.id outboundCallId,c.repo_id callerRepoId,r.name repoName,
+      b.id bindingId,b.alias,b.alias_expr aliasExpr,b.destination_expr destination,
+      b.service_path_expr servicePath,b.source_file sourceFile,b.source_line sourceLine,
+      b.helper_chain_json helperChainJson
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    JOIN service_bindings b ON b.id=c.service_binding_id AND b.repo_id=c.repo_id
+    WHERE c.id=? AND (? IS NULL OR r.workspace_id=?)`).get(
+    callId, workspaceId, workspaceId,
+  );
+  return selectedReferenceFromRow(row);
+}
+
+function selectedReferenceFromRow(
+  row: Record<string, unknown> | undefined,
+): SelectedDynamicReference | undefined {
+  const outboundCallId = numberValue(row?.outboundCallId);
+  const callerRepoId = numberValue(row?.callerRepoId);
+  const reference = referenceFromRow(
+    row, 'service_binding', 'selected_binding',
+  )[0];
+  return reference && outboundCallId !== undefined && callerRepoId !== undefined
+    ? { ...reference, outboundCallId, callerRepoId }
+    : undefined;
+}
+
+function exactRequireReferences(
+  db: Db,
+  workspaceId: number | undefined,
+  selected: SelectedDynamicReference,
+): DynamicReferenceRow[] {
+  if (!(selected.aliasExpr ?? selected.alias)) return [];
+  const rows = db.prepare(`SELECT req.alias,req.destination,req.service_path servicePath,
+      r.name repoName,'package.json' sourceFile,1 sourceLine
+    FROM cds_requires req JOIN repositories r ON r.id=req.repo_id
+    WHERE req.repo_id=? AND (? IS NULL OR r.workspace_id=?)
+    ORDER BY req.alias,req.id`).all(
+    selected.callerRepoId, workspaceId, workspaceId,
+  );
+  return rows.flatMap((row) => referenceFromRow(
+    row, 'cds_require', 'selected_binding_require', selected.bindingId,
+  ));
+}
+
+function fallbackReferences(
+  db: Db,
+  workspaceId: number | undefined,
+  callerRepoId: number | undefined,
+  callerRepo: string | undefined,
+): DynamicReferenceRow[] {
+  if (callerRepoId === undefined && callerRepo === undefined) return [];
+  const rows = db.prepare(`SELECT b.id bindingId,COALESCE(b.alias,b.alias_expr) alias,
+      b.alias_expr aliasExpr,b.destination_expr destination,b.service_path_expr servicePath,
+      'service_binding' sourceKind,r.name repoName,b.source_file sourceFile,
+      b.source_line sourceLine,b.helper_chain_json helperChainJson,0 sourcePriority
+    FROM service_bindings b JOIN repositories r ON r.id=b.repo_id
+    WHERE (? IS NULL OR r.workspace_id=?)
+      AND ((? IS NOT NULL AND r.id=?) OR (? IS NULL AND r.name=?))
+    UNION ALL
+    SELECT NULL,req.alias,req.alias,req.destination,req.service_path,
+      'cds_require',r.name,'package.json',1,NULL,1
+    FROM cds_requires req JOIN repositories r ON r.id=req.repo_id
+    WHERE (? IS NULL OR r.workspace_id=?)
+      AND ((? IS NOT NULL AND r.id=?) OR (? IS NULL AND r.name=?))
+    ORDER BY sourcePriority,repoName,sourceFile,sourceLine`).all(
+    workspaceId, workspaceId, callerRepoId, callerRepoId, callerRepoId, callerRepo,
+    workspaceId, workspaceId, callerRepoId, callerRepoId, callerRepoId, callerRepo,
+  );
+  return rows.flatMap((row) => {
+    const sourceKind = row.sourceKind;
+    return sourceKind === 'service_binding' || sourceKind === 'cds_require'
+      ? referenceFromRow(row, sourceKind, 'fallback')
+      : [];
+  });
+}
+
+function referenceFromRow(
+  row: Record<string, unknown> | undefined,
+  sourceKind: DynamicReferenceRow['sourceKind'],
+  selection: DynamicReferenceRow['selection'],
+  bindingId = numberValue(row?.bindingId),
+): DynamicReferenceRow[] {
+  const repoName = stringValue(row?.repoName);
+  if (!repoName) return [];
+  return [{
+    bindingId,
+    alias: stringValue(row?.alias),
+    aliasExpr: stringValue(row?.aliasExpr),
+    destination: stringValue(row?.destination),
+    servicePath: stringValue(row?.servicePath),
+    sourceKind,
+    selection,
+    repoName,
+    sourceFile: stringValue(row?.sourceFile),
+    sourceLine: numberValue(row?.sourceLine),
+    helperChain: parsedJson(row?.helperChainJson),
+  }];
+}
+
+function persistedBindingResolution(evidence: Record<string, unknown>): {
+  status: string;
+  candidates: Array<Record<string, unknown>>;
+  candidateCount: number;
+} {
+  const outbound = record(evidence.outboundEvidence);
+  const resolution = record(outbound.serviceBindingResolution);
+  return {
+    status: stringValue(resolution.status) ?? 'unknown',
+    candidates: recordArray(resolution.candidates),
+    candidateCount: numberValue(resolution.candidateCount) ?? 0,
+  };
+}
+
+function boundedAlternatives(
+  rows: Array<Record<string, unknown>>,
+  reportedCount: number,
+): BoundedProjection<Record<string, unknown>> {
+  const projection = projectBounded(rows, (left, right) =>
+    Number(left.bindingId ?? 0) - Number(right.bindingId ?? 0)
+    || String(left.sourceFile ?? '').localeCompare(String(right.sourceFile ?? ''))
+    || Number(left.sourceLine ?? 0) - Number(right.sourceLine ?? 0));
+  const totalCount = Math.max(reportedCount, projection.totalCount);
+  return {
+    ...projection,
+    totalCount,
+    omittedCount: Math.max(0, totalCount - projection.shownCount),
+  };
+}
+
+function parsedJson(value: unknown): unknown {
+  if (typeof value !== 'string' || value.length === 0) return undefined;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function recordArray(value: unknown): Array<Record<string, unknown>> {
+  return Array.isArray(value)
+    ? value.filter((item): item is Record<string, unknown> =>
+        Boolean(item && typeof item === 'object' && !Array.isArray(item)))
+    : [];
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}