bfa

Origin

Introduction

bfa is a pure, schema-driven data-fetching library designed to bring back the convenience of templates into modern frontends (can be additionally used for general-purpose data-fetching workflows). It bridges the gap between your frontend and backend by "reconciling" the frontend and the backend using a flexible, declarative schema system.

By defining your data requirements using typed builder classes (Int, String, Float, Bool, List, JSON), bfa dynamically compiles your constraints into a standardized payload. The core Reconcile engine then takes care of the HTTP requests, executing middlewares, and crucially validating the incoming JSON response against your schema to guarantee end-to-end type safety.

The library is completely framework-agnostic. You don't need dedicated adapters or wrappers for React, Vue, or Svelte. bfa is simple enough to retrieve validated data in a single line so you can instantly pass it to your components. It also doesn't matter what your backend passes back to the frontend, bfa will always validate the response against your schema, promptly throwing an error if the response doesn't match.

Quick Example

import { Schema, Types, Reconcile } from 'bfa';

// 1. Define your schema constraints
const userSchema = new Schema({
  id: Types.Int().min(1),
  username: Types.String().minLength(3),
});

// 2. Setup your Reconcile client with optional middleware
const api = new Reconcile('https://api.example.com/user', userSchema)
  .use(async (context, next) => {
    // Add auth headers dynamically
    context.options.headers = {
      ...context.options.headers,
      'Authorization': 'Bearer YOUR_TOKEN'
    };
    const response = await next(context);
    console.log(`[bfa] Fetched ${context.url} - Status: ${response.status}`);
    return response;
  });

// 3. Fetch and get guaranteed, validated data in one line
const data = await api.fetch(); 
// If the backend returns an invalid string or missing ID, bfa throws a clear validation error.

How It Compares to Existing Solutions

bfa fills a unique space in the modern ecosystem, focusing on pure simplicity and decoupling:

• vs. GraphQL (Apollo/Relay): GraphQL requires adopting a specific query language and setting up a heavy client cache. bfa relies on pure JavaScript objects and maps effortlessly to standard REST-like endpoints without the boilerplate.
• vs. tRPC: tRPC is fantastic for full-stack TypeScript monorepos, but it deeply couples your frontend and backend. bfa allows you to define your expected contract strictly on the client side, making it perfect for integrating with third-party APIs or backends written in other languages (Go, Python, Rust).
• vs. Zod + Fetch / Axios: While you can manually write fetch wrappers and pass the results to a Zod schema, bfa combines the payload generation (compilation), the fetch execution, middleware pipelines, and validation into a single cohesive Reconcile lifecycle.

Roadmap & Future Suggestions

bfa intentionally avoids bloat like framework-specific hooks, keeping the footprint minimal. However, here are a few logical steps for the future that maintain its core philosophy:

Performance-Oriented Improvements

• Schema Compilation to Fast Validation Functions: Compile schemas into reusable JavaScript validation functions for faster validation, especially with large or deeply nested data.
• Async/Batched Validation for Large Payloads: Provide an async validation mode for very large arrays/objects to keep UIs responsive and avoid blocking the main thread.

Generality & Feature-Oriented Improvements

• Complex Primitives: Expand the Types dictionary to include Date (with auto-parsing from ISO strings), Enum, Email, and UUID for more robust validations.
• Better Error Reporting: Include full paths and context in validation errors, and optionally collect all errors instead of failing fast.
• Schema Introspection & Serialization: Allow schemas to be serialized to JSON and introspected at runtime for auto-generating forms, docs, or backend integration.