data-cap

Your application's data should have an owner.

data-cap treats application data as a capability-owned contract: its fields, the operations that acquire or change them, and the code that depends on them.

Existing tools help with fetching, caching, and managing data.

data-cap answers why the data exists, who owns it, and where it is used.

You keep everything you have. data-cap does not replace TanStack Query, Redux, Zustand, Apollo, or plain fetch + useState. It gives those tools a stable contract around the data they already manage.

See it run

Define a capability around the data your application owns:

const user = createData({
  fields: {
    profile: UserProfileSchema,
    preferences: UserPreferencesSchema,
  },

  getters: {
    load: async () => fetchUser(),
  },

  mutators: {
    updatePreferences: async (preferences) => {
      await updateUserPreferences(preferences)
    },
  },
})

Then inspect the application as a whole:

$ npx data-cap --root . --include "src/**"

Discovered 1 active capability(ies).

Manifest changes since last execution:

  No changes.

Wrote docs: docs/DATA.md
Wrote dependency & ownership report: docs/OWNERSHIP.md

The generated artifacts make the contract visible to developers, reviewers, and automated contributors.

Why it exists

Application data tends to outlive the code that first introduced it.

A field gets added to an API response. A second component starts depending on it. A mutation changes it. A cache begins supplying it. Eventually nobody can easily answer:

• Why does this data exist?
• Who owns it?
• What can change it?
• Where is it used?

Existing data tools answer different questions. Fetching libraries retrieve data. Caches manage freshness and reuse. State libraries manage application state.

data-cap adds the missing ownership layer.

Quick start

Install the package:

npm install data-cap

Define a capability around data your application owns:

const account = createData({
  fields: {
    balance: 0,
    status: "active" as "active" | "suspended",
  },

  getters: {
    load: async () => getAccount(),
  },

  mutators: {
    suspend: async () => suspendAccount(),
  },
})

Use the capability from your application without coupling its ownership to a particular transport, database, framework, or state library.

For the full API and integration patterns, see the Guide.

Why not just use your existing data library?

| Tool | Primary question | | --------------- | ---------------------------------------------------------------- | | fetch | How do I retrieve this? | | TanStack Query | How do I fetch and cache this? | | Redux / Zustand | How do I manage this state? | | Apollo | How do I manage GraphQL data? | | data-cap | Why does this data exist, who owns it, and where is it used? |

These concerns can coexist.

For example, TanStack Query can remain responsible for fetching and caching while data-cap defines the application's ownership contract around the resulting data.

From one capability to a whole application

A capability can be inspected independently or as part of the application.

The build tooling can generate a manifest, documentation catalog, dependency and ownership report, and other artifacts that make data relationships visible across the repository.

See the examples/ directory for complete applications and the migration guides.

You probably don't need it when

data-cap is probably unnecessary if your application is small enough that data ownership, dependencies, and usage are already obvious.

It becomes useful when data crosses component, feature, team, or system boundaries and those relationships become difficult to see.

Works with automated contributors

Generated manifests and ownership documentation give automated contributors repository-local context about application data.

That makes data changes easier to inspect, review, and govern without relying entirely on tribal knowledge.

Status

data-cap is pre-1.0.

The core runtime, build tooling, CLI, ESLint integration, manifest generation, documentation generation, and ownership analysis are implemented and tested. createData is currently Experimental; lower-level runtime primitives are Stable.

Learn more

• Guide - Concepts, usage, and integration patterns
• Architecture - Runtime and build architecture
• Migrations - Adoption from common data-management patterns
• API documentation - Generated API reference
• Examples - Complete working examples
• Architecture decisions - Design rationale
• Security - Security policy
• Contributing - Development and contribution workflow
• Releasing - Release process
• Versioning - Versioning policy

If this is useful

If data-cap helps make your application's data easier to understand and maintain, consider giving the project a star or sharing it with someone working on application architecture.

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening an issue or pull request.

License

See LICENSE.