Adding Core Functions

Adding Core Functions

When to Use

• Creating new ADT operations (CRAUD, discovery, preview)
• Adding pure business logic functions
• Implementing library-consumable functionality

One Function Per File

Each core function gets its own file. No multi-function files.

Location: src/​core/​{domain}/​{function}.ts

core/​adt/
├── index.ts              # Barrel exports
├── types.ts              # Shared types (AdtRequestor, ObjectConfig)
├── helpers.ts            # Internal helpers (not exported from barrel)
│
├── craud/
│   ├── read.ts           → readObject()
│   ├── create.ts         → createObject()
│   └── ...
│
└── discovery/
    ├── packages.ts       → getPackages()
    └── ...

Import Hierarchy

Files must follow this hierarchy (no circular dependencies):

types.ts           (shared types, no imports from package)
    ↓
helpers.ts         (internal utilities, imports types)
    ↓
subfolder files    (import ../​types and ../​helpers)
    ↓
index.ts           (barrel exports, imports from subfolders)

Relative path patterns:

• ../​types — shared types
• ../​helpers — shared helpers
• ../​../​utils/​xml — core utilities
• ../​../​../​types/​result — global types

Function File Pattern

// src/​core/​adt/​discovery/​packages.ts

import type { AdtRequestor } from '../​types';
import type { AsyncResult } from '../​../​../​types/​result';

export interface Package {
    name: string;
    description: string;
}

export async function getPackages(
    requestor: AdtRequestor,
    filter?: string
): AsyncResult<Package[]> {
    // Implementation
    const response = await requestor.get('/​packages', { params: { filter } });

    if (response.error) {
        return [null, response.error];
    }

    return [parsePackages(response.data), null];
}

// Internal helper (not exported)
function parsePackages(xml: string): Package[] {
    // ...
}

Return Type Convention

Use Go-style error tuples:

import type { AsyncResult } from '../​../​../​types/​result';

// Returns [data, null] on success, [null, error] on failure
export async function someOperation(): AsyncResult<Data> {
    // ...
}

Barrel Exports

Add to index.ts for public API:

// src/​core/​adt/​index.ts

// Types
export type { AdtRequestor, ObjectConfig } from './​types';

// Discovery
export { getPackages } from './​discovery/​packages';
export { getTree } from './​discovery/​tree';

// CRAUD
export { readObject } from './​craud/​read';
export { createObject } from './​craud/​create';

Internal Helpers

Helpers not exported from barrel go in helpers.ts:

// src/​core/​adt/​helpers.ts

import type { AdtRequestor } from './​types';

// Internal - not exported from index.ts
export function buildObjectUri(name: string, extension: string): string {
    // ...
}

Checklist

- [ ] Create function file in src/​core/​{domain}/​{subfolder}/
- [ ] Define types at top of file or in ../​types.ts
- [ ] Use AsyncResult return type for async functions
- [ ] Follow import hierarchy (no circular deps)
- [ ] Export from index.ts if public API
- [ ] Put internal helpers in helpers.ts
- [ ] Run typecheck: bun run typecheck