drizzle-include

Create Drizzle relational query with objects from typed relation path tuples.

The API is inspired by the include field from the Stripe API, where clients can request optional nested values that are not returned by default. In the same spirit, drizzle-include lets callers request only the relation paths they need while the library turns those paths into the Drizzle with object.

Usage

import { drizzleWith } from "drizzle-include";

const usersWith = drizzleWith(db).users.with({
  posts: {
    columns: { id: true, title: true },
    with: {
      comments: {
        with: {
          author: true,
        },
      },
    },
  },
  comments: true,
});

const withValue = usersWith.parse(["posts.comments.author", "comments"] as const);

await db.query.users.findMany({
  with: withValue,
});

The generated value is:

{
  posts: {
    columns: { id: true, title: true },
    with: {
      comments: {
        with: {
          author: true,
        },
      },
    },
  },
  comments: true,
}

Standalone Parser

Use createWithParser when you already have a Drizzle with type or do not need the db.query helper shape.

import { createWithParser } from "drizzle-include";

const usersWith = createWithParser({
  posts: {
    with: {
      comments: true,
    },
  },
});

const withValue = usersWith.parse(["posts.comments"] as const);

You can also provide an explicit template type:

const usersWith = createWithParser<UserWith>()({
  posts: {
    with: {
      comments: true,
    },
  },
});

Behavior

• parse accepts literal relation path tuples.
• Literal relation paths are type-checked against the with template.
• Ancestors required to reach requested descendants are included.
• Unrequested descendants are omitted.
• Relation options such as columns, where, orderBy, limit, and extras are preserved for selected relations.
• Duplicate and overlapping relation paths merge into one with object.
• A selected relation with no options collapses to true.
• The with template is never mutated.

Types

import type { ParsedWith, RelationPath, WithParser, WithTemplate } from "drizzle-include";

Development

vp install
vp test
vp check
vp pack