Collection relations

A many relation says that the foreign key lives on the target:

import { entity, many } from 'foldkit-remote-drizzle'

const Comment = entity('Comment', comments)

const Post = entity('Post', posts, {
  relations: {
    comments: many(Comment, {
      foreignKey: comments.postId,
      localKey: posts.id,
    }),
  },
})

A normal collection read batches children across all requested parents instead of issuing one query per parent. The wire value remains normalized refs:

Post:p1.comments = ["Comment:c1", "Comment:c2"]

Collection relations may also declare:

• orderBy — defaults to target id;
• where — a static filter, such as excluding soft-deleted rows.

Many-to-many#

Use a through table when the relation is many-to-many:

import { entity, manyToMany } from 'foldkit-remote-drizzle'

const Tag = entity('Tag', tags)

const Post = entity('Post', posts, {
  relations: {
    tags: manyToMany(Tag, {
      through: postTags,
      localColumn: postTags.postId,
      foreignColumn: postTags.tagId,
    }),
  },
})

The Source joins through the link table to the target, drops dangling through rows, and emits target refs.

Principal-scoped collection policy#

A collection can add a per-principal SQL predicate:

import { eq } from 'drizzle-orm'

const PostSource = source(Post, {
  policies: {
    comments: principal => eq(comments.visibleTo, principal.id),
  },
})

That predicate is combined with the relation's static where. Policies are only valid for collection relations; putting one on a singular relation is rejected at definition time because it would not filter the target read correctly.