UCD.js Docs

Shared

Architecture notes for @ucdjs-internal/shared

@ucdjs-internal/shared holds internal cross-package helpers.

Role

  • Provides reusable internal utilities for async work, fetch behavior, filtering, files, guards, and hashing.
  • Supports workspace packages without promising external stability.
  • Sits below domain packages such as client, store, and pipeline tooling.

Utils

The stable public facade re-exports a small subset of shared helpers.

Client

Client resources rely on customFetch and guards from shared.

UCD Store

Store operations depend heavily on wrapTry, path filters, and file helpers.

Package Layers

See why shared stays internal and below business packages.

Mental Model

This package is the workspace’s implementation toolbox.

It is deliberately broad, but the exports still cluster into a few clear families:

  • async helpers: concurrency limiting, wrapTry, tryOr
  • fetch helpers: customFetch, normalized fetch errors, schema-aware responses
  • path/file helpers: flattening, normalization, tree filtering
  • glob and filter helpers
  • small guards and serialization helpers

Helper Families

@ucdjs-internal/shared

async/*

fetch/*

files.ts

filter.ts / glob.ts

guards.ts

json.ts

version.ts

Method Flows

customFetch.safe()

optional schema validationfetch()executeFetch()customFetch.safe()optional schema validationfetch()executeFetch()customFetch.safe()alt[schema invalid]opt[schema provided and success status]alt[HTTP status >= 400][success]alt[network/request failure][HTTP response received]CallercustomFetch.safe(request, options)executeFetch(...)fetch(request, normalized options)throw / rejectnormalized FetchError{ data: null, error }Responseparse body by response typesafeParseAsync(response.data)validation issuesFetchSchemaValidationError{ data: null, error }FetchError{ data: null, error, response }FetchResponse{ data, error: null, response }Caller

createPathFilter(options)

picomatchfilter configcreatePathFilter()picomatchfilter configcreatePathFilter()CallercreatePathFilter({ include, exclude, disableDefaultExclusions })normalize include/exclude patternsapply default excluded extensions unless disabledfilter functionfilter(path, extraOptions)evaluate normalized path against include + exclude rulestrue / falseCaller

wrapTry(operation)

operationwrapTry()operationwrapTry()alt[sync or asyncsuccess][sync or async failure]CallerwrapTry(operation)execute operationvalue[value, null]throw / reject[null, error]Caller

tryOr({ try, err })

err handlertry handlertryOr()err handlertry handlertryOr()alt[try succeeds][try fails]CallertryOr({ try, err })execute try handlervaluevaluethrow / rejectexecute err handlerfallback valuefallback valueCaller

Internal Boundary

not stable public API

shared internal helpers

client

ucd-store

tooling / tests / pipelines

external consumers

Testing Use

The highest-value tests here are:

  • fetch normalization, retry, timeout, and schema-validation branches
  • filter/path matching edge cases and default exclusions
  • wrapTry / tryOr sync and async behavior
  • file tree normalization and flattening helpers

UCDJS Scripts

Architecture notes for @ucdjs/ucdjs-scripts

Shared UI

Architecture notes for @ucdjs-internal/shared-ui

On this page

RoleRelated DocsMental ModelHelper FamiliesMethod FlowscustomFetch.safe()createPathFilter(options)wrapTry(operation)tryOr({ try, err })Internal BoundaryTesting Use