Barrits

https://github.com/zuccadev-labs/barrits
Admin
Package-first functional automation for TypeScript/JavaScript monorepos — AST-level discovery graph,...
Tokens:112,524
Snippets:1,143
Trust Score:7.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Use named exports, no default exports
- Bilingual documentation: [EN] / [ES] in all JSDoc and markdown
- Conventional commits: feat:, fix:, refactor:, chore:, docs:
- Use @barrits-trait JSDoc annotations for trait discovery and composition
- Create barrits.config.ts at project root for build configuration
- Run npm test after changes to validate 946+ tests pass

================
CODE SNIPPETS
================
### Example Certification Loop

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-runtime-quality/SKILL.md

Iterate over example directories and run the appropriate build or start command based on the presence of package.json or deno.json. This ensures each example passes its build/run validation.

```bash
for dir in packages/sdk/ts_js/examples/*/; do
  echo "=== $dir ==="
  cd "$dir"
  if [ -f "package.json" ]; then
    npm run build --if-present
  elif [ -f "deno.json" ]; then
    deno task start
  fi
done
```

--------------------------------

### Setup Barrits SDK

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-onboarding/SKILL.md

Clones the Barrits repository, installs dependencies, builds the SDK, and runs the test suite. Requires Node.js >= 18, npm >= 11, Deno >= 2.x, and optionally Bun >= 1.3.

```bash
git clone <repo-url>
cd barrits
npm install
npm run build
npm test
```

--------------------------------

### Run cross-runtime example checks

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-cross-runtime-validation/SKILL.md

Builds the Deno example and runs the Node.js example to verify cross-runtime behavior.

```bash
deno task build # Inside example-deno
```

```bash
node src/main.js # Inside example-nodejs
```

--------------------------------

### Install PlantUML

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/architecture/README.md

Install PlantUML to render the C4 architecture diagrams. Provides options for VSCode extension, CLI installation via brew or scoop, and a Java alternative.

```bash
# VSCode: install "PlantUML" extension
# CLI: brew install plantuml / scoop install plantuml
# CLI alternative: java -jar plantuml.jar
```

--------------------------------

### Install @zuccadev-labs/barrits with npm, yarn, or pnpm

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-package-consumer-onboarding/SKILL.md

Install the package using your preferred package manager. The commands are alternatives; choose one.

```bash
npm install @zuccadev-labs/barrits
# or
yarn add @zuccadev-labs/barrits
# or
pnpm add @zuccadev-labs/barrits
```

--------------------------------

### topK usage example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09b-api-reference-algorithms.md

Imports topK from @zuccadev-labs/barrits and calls it with a collection and a limit of 5. This example appears in example-deno/main.ts and example-bun/src/main.ts.

```TypeScript
import { topK } from "@zuccadev-labs/barrits";
topK(candidates, 5);
```

--------------------------------

### Run SolidJS development server and build

Source: https://github.com/zuccadev-labs/barrits/blob/dev/packages/sdk/ts_js/examples/example-solid/README.md

Commands to start the SolidJS development server and generate the production build.

```bash
npm run dev    # Start the SolidJS development server
npm run build  # Generate the production build
```

--------------------------------

### Run Vue development server and build

Source: https://github.com/zuccadev-labs/barrits/blob/dev/packages/sdk/ts_js/examples/example-vue/README.md

Commands to start the Vue development server and generate the production build.

```bash
npm run dev    # Start the Vue development server
npm run build  # Generate the production build
```

--------------------------------

### Install Barrits from npm

Source: https://github.com/zuccadev-labs/barrits/blob/dev/README.md

Install the Barrits package from npm. For Deno, use JSR instead.

```bash
npm install @zuccadev-labs/barrits
```

--------------------------------

### Run Development Server and Build

Source: https://github.com/zuccadev-labs/barrits/blob/dev/packages/sdk/ts_js/examples/example-react/README.md

Commands to start the development server with the Vite plugin active and to generate the production build with artifact materialization.

```bash
npm run dev    # Start the development server with the plugin active
npm run build  # Generate the production build with artifact materialization
```

--------------------------------

### Package-first configuration with defineBarritsConfig

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-integration-points/SKILL.md

Example barrits.config.mjs that enables auto-discovery with runtime placeholder, autoManifest, custom automationDirectory, and discoveryRoots.

```javascript
import { defineBarritsConfig } from '@zuccadev-labs/barrits';

export default defineBarritsConfig({
  runtime: '<node|deno|bun|react|vue|solid|svelte>',
  autoManifest: true,
  automationDirectory: '.cache/barrits',
  discoveryRoots: ['src'],
});
```

--------------------------------

### Run and build the example-tauri app

Source: https://github.com/zuccadev-labs/barrits/blob/dev/packages/sdk/ts_js/examples/example-tauri/README.md

Commands to run the example Tauri application in development and production modes. Use npm run dev for the web server, npm run build for the web production build, npm run tauri:dev to launch the desktop app in development, and npm run tauri:build for the desktop production build.

```bash
npm run dev         # Start the web development server
npm run build       # Generate the web production build
npm run tauri:dev   # Launch the desktop application in development mode
npm run tauri:build # Generate the desktop production build
```

--------------------------------

### Run example-bun commands

Source: https://github.com/zuccadev-labs/barrits/blob/dev/packages/sdk/ts_js/examples/example-bun/README.md

Commands to run the example-bun project: dev/showcase for the full showcase, test for the 14 tests, build via the Barrits Bun CLI adapter, and inspect the project manifest.

```bash
bun run dev              # Execute the main entrypoint (full showcase)
bun run showcase         # Same as dev
bun test                 # Run 14 tests (traits, scripts, showcase)
bun run build            # Build via the Barrits Bun CLI adapter
bun run inspect          # Inspect the project manifest
```

--------------------------------

### Safe Instantiation with createBarrits()

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/05-automation-and-configuration.md

Use this snippet when the `namespace` field is configured to get a typed, isolated object without polluting global scope. The example shows importing `createBarrits` and calling it in an async boot function, with IDE autocomplete guaranteed under the configured namespace.

```ts
import { createBarrits } from "@zuccadev-labs/barrits";

const boot = async () => {
  const system = await createBarrits();
  // IDE autocomplete is fully guaranteed under the configured namespace
  system.myApp.logic.orderBy(items, criteria);
};
```

--------------------------------

### createTraitDescriptorFromJsDoc example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09d-api-reference-traits-and-composition.md

Creates a trait descriptor from an existing JSDoc block. The example passes a JSDoc string with the same tags as the first example, but uses the JSDoc-based factory.

```TypeScript
import { createTraitDescriptorFromJsDoc } from "@zuccadev-labs/barrits";

/**
 * @barrits-trait
 * @barrits-provides auth-session, database-adapter
 * @barrits-conflicts legacy-adapter
 * @barrits-state currentUser, connectionPool
 * @barrits-consumes logger, config
 */
export const authTrait = createTraitDescriptorFromJsDoc(`
/**
 * @barrits-trait
 * @barrits-provides auth-session, database-adapter
 * @barrits-conflicts legacy-adapter
 * @barrits-state currentUser, connectionPool
 * @barrits-consumes logger, config
 */
`);
```

--------------------------------

### diffMs(start, end)

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09b-api-reference-algorithms.md

Computes the millisecond difference between two dates (end - start).

```APIDOC
## diffMs(start, end)

### Description
Computes the millisecond difference between two dates (`end - start`).

### Method
Function

### Signature
`diffMs(start: Date, end: Date): number`

### Parameters
- **start** (Date) - Required - The starting date.
- **end** (Date) - Required - The ending date.

### Return Value
- **number** - The difference in milliseconds.

### Example
```ts
import { diffMs } from "@zuccadev-labs/barrits";

const start = new Date("2026-04-21T00:00:00Z");
const end = new Date("2026-04-22T00:00:00Z");
diffMs(start, end); // 86400000 (24 hours)
```
```

--------------------------------

### createBarrits(options?)

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09a-api-reference-package-config.md

Initializes the SDK by dynamically building the context based on the configuration file. Enables renaming the root system namespace while keeping IDE and typings tooling intact.

```APIDOC
## createBarrits(options?)

### Description
Initializes the SDK by dynamically building the context based on the configuration file. Enables renaming the root system namespace (dynamic namespace injection) while keeping the IDE and typings tooling intact.

### Parameters
- **options** (object) - Optional - Initialization options.

### Request Example
```ts
import { createBarrits } from "@zuccadev-labs/barrits";

const app = await createBarrits();
// app.logic, app.traits, app.routes — available under the configured namespace
// The returned object also always includes `barrits` and `brt` (fixed aliases) plus `config`.
```

### Response
Returns a promise that resolves to the initialized SDK context object.

### Appears In
- `examples/example-nodejs/` main scripts as the namespace-aware boot entry.
```

--------------------------------

### Deno Task Commands for Barrits Example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/packages/sdk/ts_js/examples/example-deno/README.md

Run the orchestration entrypoint, test suite, build, inspect, and demos using `deno task`. Each command triggers a specific workflow: `dev` executes the orchestration entrypoint, `test` runs the automated test suite, `build` builds and inspects the contract graph, `inspect` inspects the build manifest, `demo:openapi` generates an OpenAPI schema from trait descriptors, and `demo:ioc` runs the dependency injection demo.

```bash
deno task dev           # Execute the orchestration entrypoint
deno task test          # Run the automated test suite
deno task build         # Build and inspect the contract graph
deno task inspect       # Inspect the build manifest
deno task demo:openapi  # Generate OpenAPI schema from trait descriptors
deno task demo:ioc      # Run the dependency injection demo
```

--------------------------------

### paginate usage example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09b-api-reference-algorithms.md

Imports paginate from @zuccadev-labs/barrits and calls it with a collection and an options object specifying page and limit. This example appears in example-nodejs/src/examples/selection/real-selection-cases.mjs.

```TypeScript
import { paginate } from "@zuccadev-labs/barrits";
paginate(items, { page: 1, limit: 10 });
```

--------------------------------

### createBuildManifestSummary usage

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09a-api-reference-package-config.md

Generates a condensed summary of the build manifest. The summary exposes a domains property.

```ts
import { createBuildManifestSummary } from "@zuccadev-labs/barrits";

const summary = createBuildManifestSummary(manifest);
console.log(summary.domains);
```

--------------------------------

### averageBy usage example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09b-api-reference-algorithms.md

Imports averageBy from @zuccadev-labs/barrits and calls it with a collection and a projector function that extracts the latency property. This example appears in example-deno/main.ts and example-bun/src/main.ts.

```TypeScript
import { averageBy } from "@zuccadev-labs/barrits";
averageBy(metrics, (m) => m.latency);
```

--------------------------------

### Read the build manifest

Source: https://github.com/zuccadev-labs/barrits/blob/dev/packages/sdk/ts_js/README.md

Create a summary from the build manifest and log the domains.

```ts
import { createBuildManifestSummary } from "@zuccadev-labs/barrits";
import manifest from "virtual:barrits/manifest";

const summary = createBuildManifestSummary(manifest);
console.log(summary.domains);
```

--------------------------------

### composePipeline example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09d-api-reference-traits-and-composition.md

Composes a pipeline of sequential transformations. The example passes an initial value and three transformation functions (normalize, filter, rank) to composePipeline.

```TypeScript
import { composePipeline } from "@zuccadev-labs/barrits";

const result = composePipeline(
  rawData,
  (data) => normalize(data),
  (data) => filter(data),
  (data) => rank(data)
);
```

--------------------------------

### createBuildManifestSummary(manifest)

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09a-api-reference-package-config.md

Generates a condensed summary of the build manifest.

```APIDOC
## createBuildManifestSummary(manifest)

### Description
Generates a condensed summary of the build manifest.

### Method
Function

### Signature
createBuildManifestSummary(manifest: BuildManifest): BuildManifestSummary

### Parameters
#### Path Parameters
- **manifest** (BuildManifest) - Required - The build manifest to summarize.

### Request Example
```ts
import { createBuildManifestSummary } from "@zuccadev-labs/barrits";

const summary = createBuildManifestSummary(manifest);
console.log(summary.domains);
```

### Response
#### Success Response
- **BuildManifestSummary** - The condensed summary.

#### Response Example
```ts
{
  domains: [...]
}
```
```

--------------------------------

### Run Svelte development server and build

Source: https://github.com/zuccadev-labs/barrits/blob/dev/packages/sdk/ts_js/examples/example-svelte/README.md

Commands to start the Svelte development server and generate the production build. The first command runs the dev server, the second builds the production output.

```bash
npm run dev    # Start the Svelte development server
npm run build  # Generate the production build
```

--------------------------------

### movingAverageSeries example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09b-api-reference-algorithms.md

Calculates a moving average over a typed time series using the movingAverageSeries function from @zuccadev-labs/barrits. The example passes a price series and a window size of 5.

```TypeScript
import { movingAverageSeries } from "@zuccadev-labs/barrits";
movingAverageSeries(priceSeries, 5);
```

--------------------------------

### composeTraitDescriptors example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09d-api-reference-traits-and-composition.md

Composes multiple trait descriptors into a final merged structure. The example creates an array of two trait descriptors and passes them to composeTraitDescriptors with an input option.

```TypeScript
import { composeTraitDescriptors, createTraitDescriptor } from "@zuccadev-labs/barrits";

const traits = [
  createTraitDescriptor({ name: "Auth", provides: ["session"] }),
  createTraitDescriptor({ name: "DB", provides: ["connection"] })
];

const result = composeTraitDescriptors({ input: traits });
```

--------------------------------

### Read build manifest with createBuildManifestSummary

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/03-examples-and-walkthroughs.md

Imports the virtual manifest and creates a summary. Logs resolved domains and public export surfaces.

```ts
import { createBuildManifestSummary } from "@zuccadev-labs/barrits";
import manifest from "virtual:barrits/manifest";

const summary = createBuildManifestSummary(manifest);
console.log(summary.domains);   // Resolved domains
console.log(summary.exports);   // Public export surfaces
```

--------------------------------

### movingAverage example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09b-api-reference-algorithms.md

Calculates a moving average over a simple numeric sequence using the movingAverage function from @zuccadev-labs/barrits. The example passes an array and a window size of 2, producing [15, 25, 35].

```TypeScript
import { movingAverage } from "@zuccadev-labs/barrits";
movingAverage([10, 20, 30, 40], 2); // [15, 25, 35]
```

--------------------------------

### parseTraitDescriptorJsDoc example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09d-api-reference-traits-and-composition.md

Parses a JSDoc string into structured trait metadata. The example shows a JSDoc block with @barrits-trait, @barrits-provides, and @barrits-state tags, and the resulting metadata object with provides and state arrays.

```TypeScript
import { parseTraitDescriptorJsDoc } from "@zuccadev-labs/barrits";

const jsDoc = `
 * @barrits-trait
 * @barrits-provides auth-session
 * @barrits-state user
`;

const metadata = parseTraitDescriptorJsDoc(jsDoc);
// Returns: { provides: ["auth-session"], state: ["user"] }
```

--------------------------------

### readBuildManifestSummary(path, readTextFile)

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09c-api-reference-consume-and-adapters.md

Reads the manifest and returns its summary directly. This function is useful when you only need the summary rather than the full manifest.

```APIDOC
## readBuildManifestSummary(path, readTextFile)

### Description
Reads the manifest and returns its summary directly.

### Parameters
- **path** (string) - Required - The path to the build manifest file.
- **readTextFile** (function) - Required - An async function that reads a file and returns its text content.

### Returns
- **Promise<BarritsBuildManifestSummary>** - The summary of the build manifest.

### Appears in
- `examples/example-tauri/src/main.ts`
```

--------------------------------

### createTraitDescriptor example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09d-api-reference-traits-and-composition.md

Creates a reusable trait descriptor with explicit metadata. The example shows a JSDoc block with @barrits-trait, @barrits-provides, @barrits-conflicts, @barrits-state, and @barrits-consumes tags, and the descriptor object with matching fields.

```TypeScript
import { createTraitDescriptor } from "@zuccadev-labs/barrits";

/**
 * @barrits-trait
 * @barrits-provides auth-session, database-adapter
 * @barrits-conflicts legacy-adapter
 * @barrits-state currentUser, connectionPool
 * @barrits-consumes logger, config
 */
export const authTrait = createTraitDescriptor({
  name: "AuthDomain",
  provides: ["auth-session", "database-adapter"],
  conflicts: ["legacy-adapter"],
  state: ["currentUser", "connectionPool"],
  consumes: ["logger", "config"]
});
```

--------------------------------

### mergeTraits example

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09d-api-reference-traits-and-composition.md

Merges multiple trait descriptors into a single consolidated result. The example creates two traits (Auth and Database) and merges them, with a comment noting the result contains combined provides and state.

```TypeScript
import { mergeTraits, createTraitDescriptor } from "@zuccadev-labs/barrits";

const authTrait = createTraitDescriptor({
  name: "Auth",
  provides: ["session"],
  state: ["user"]
});

const dbTrait = createTraitDescriptor({
  name: "Database",
  provides: ["connection"],
  state: ["pool"]
});

const result = mergeTraits(authTrait, dbTrait);
// result contains combined provides, state, etc.
```

--------------------------------

### Build and verify the industrialized core

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-cross-runtime-validation/SKILL.md

Runs the build and test suite from the SDK root to validate the core functionality.

```bash
npm run build && npm test
```

--------------------------------

### Skill Markdown Template

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/investigations/EN/packages/ts_js/10-forensic-integral-audit.md

Standard structure for a barrits skill file. Includes metadata fields (version, last updated, tags, target agents), context, prerequisites, procedure steps, and an examples section with a bash usage example.

```markdown
# Skill: barrits-<name>

## Metadata
- **Version**: 1.0.0
- **Last updated**: 2026-06-29
- **Tags**: #testing, #node, #deno
- **Target agents**: code-reviewer, maintainer

## Context
What problem does this skill solve? When to use it?

## Prerequisites
- Required tools/configuration
- Skills to execute beforehand

## Procedure
1. Step 1: ...
2. Step 2: ...
3. Step 3: ...

## Examples
```bash
# Usage example
```
```

--------------------------------

### Build and verify SDK

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-maintainer-full-cycle/SKILL.md

Runs build, typecheck, tests, and JSR dry-run from the SDK package directory.

```bash
cd packages/sdk/ts_js
npm run build
npm run typecheck
npm test
```

```bash
npm run publish:jsr:dry-run
```

--------------------------------

### Rollup plugin configuration

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-integration-points/SKILL.md

Example rollup.config.mjs that imports and uses barritsRollupPlugin.

```javascript
// rollup.config.mjs
import { barritsRollupPlugin } from '@zuccadev-labs/barrits/rollup';

export default {
  plugins: [barritsRollupPlugin()],
};
```

--------------------------------

### loadBarritsConfig()

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/users/EN/packages/ts_js/09a-api-reference-package-config.md

Loads the project configuration from disk. Solves tooling, CLI, and automation resolving the configuration without duplicating file-reading logic.

```APIDOC
## loadBarritsConfig()

### Description
Loads the project configuration from disk. Solves tooling, CLI, and automation resolving the configuration without duplicating file-reading logic.

### Parameters
None.

### Response
Returns the loaded configuration object.

### Appears In
- Internal flows and documented in `06-commands-and-runtimes.md`
```

--------------------------------

### Webpack plugin configuration

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-integration-points/SKILL.md

Example webpack.config.js that imports and uses BarritsWebpackPlugin via require.

```javascript
// webpack.config.js
const { BarritsWebpackPlugin } = require('@zuccadev-labs/barrits/webpack');

module.exports = {
  plugins: [new BarritsWebpackPlugin()],
};
```

--------------------------------

### esbuild plugin configuration

Source: https://github.com/zuccadev-labs/barrits/blob/dev/docs/agents/skills/barrits-integration-points/SKILL.md

Example esbuild.config.mjs that imports and uses barritsEsbuildPlugin in an esbuild build.

```typescript
// esbuild.config.mjs
import { barritsEsbuildPlugin } from '@zuccadev-labs/barrits/esbuild';
import * as esbuild from 'esbuild';

await esbuild.build({
  plugins: [barritsEsbuildPlugin()],
});
```
Tokens:
Raw