Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Collections

View as Markdownllms.txt

A collection is a list of models, such as the posts a query returned. In Strutvane a collection is a plain JavaScript array: Post.query().get() gives you Post[]. Every array method you already know (map, filter, find, some, reduce, toSorted) works, fully typed, and there’s no special class to learn.

Use this page when you have a list in memory and want to reshape it: pick out titles, group posts by status, look rows up by id, or split a list into batches.

app/http/controllers/post.controller.ts (excerpt)
import { Post } from '../../models/post.ts'
const posts = await Post.query().orderBy('title').get()
const titles = posts.map((post) => post.title)
console.log(titles)

What you’ll see:

[ 'Alpha', 'Beta', 'Delta 100%', 'Gamma' ]

titles is typed string[], because post.title is a string column.

Every example below starts from const posts = await Post.query().get().

You want Laravel Collection Strutvane (plain array)
One column from every row $posts->pluck('title') posts.map((post) => post.title)
Only some rows $posts->filter(fn ($p) => $p->isPublished) posts.filter((post) => post.isPublished)
The first match $posts->firstWhere('status', 'draft') posts.find((post) => post.status === 'draft')
Whether any / all match contains, every posts.some(...), posts.every(...)
How many $posts->count() posts.length
Empty? $posts->isEmpty() posts.length === 0
Sorted copy $posts->sortBy('title') posts.toSorted((a, b) => a.title.localeCompare(b.title))
Ids $posts->modelKeys() posts.map((post) => post.id)
JSON $posts->toJson() JSON.stringify(posts) (each model’s toJSON() runs)

Object.groupBy (built into Node 24) splits a list into groups by a key:

const byStatus = Object.groupBy(posts, (post) => post.status)
console.log(Object.keys(byStatus), byStatus.draft?.length)

What you’ll see (the group order follows the rows’ order):

[ 'published', 'draft' ] 2

A Map gives you fast lookups by key (Laravel’s keyBy):

const byId = new Map(posts.map((post) => [post.id, post]))
console.log(byId.get(1)?.title)
// → Alpha

Remember that decimal columns are exact strings (see Casts). Convert them deliberately, and round only at the end:

// projects.budget is t.decimal('budget', 12, 2), read as '1200.50', '300.25', …
const projects = await runWithTenant(teamId, () => Project.all())
const totalCents = projects.reduce((sum, project) => sum + Math.round(Number(project.budget) * 100), 0)
console.log((totalCents / 100).toFixed(2))
// → 1500.75

Working in whole cents keeps floating-point rounding out of the total.

To send a list to another service 100 at a time (Laravel’s chunk(100)):

for (let start = 0; start < posts.length; start += 100) {
const batch = posts.slice(start, start + 100)
await searchIndex.upload(batch.map((post) => post.toJSON())) // your own service
}

Filtering, sorting and counting in JavaScript means loading every row first. For anything bigger than a handful of rows, ask the database instead:

Instead of Write
(await Post.all()).filter((p) => p.status === 'draft') await Post.where('status', 'draft').get()
(await Post.all()).length await Post.query().count()
(await Post.all()).slice(0, 10) await Post.query().limit(10).get()
(await Post.all()).some((p) => p.slug === slug) await Post.query().where('slug', slug).exists()
counting each user’s posts in a loop await User.query().withCount('posts').get()

The database only sends the rows you need, and it can use its indexes.

Load a relationship for a whole list at once, never inside a loop. The best place is the query itself, which also gives the list the right type:

const posts = await Post.query().with('author', 'tags').latest().limit(20).get() // 3 queries for all 20 posts
const names = posts.map((post) => post.author?.name) // typed: (string | undefined)[]

If you already have the list, loadMany(posts, 'author') fills it in with one query (see Relationships).

An array holds every row in memory. For a table with millions of rows, page through it with a cursor so only one page is in memory at a time:

app/jobs/reindex-posts.ts (excerpt)
let cursor: string | undefined
do {
const page = await Post.query().orderBy('id').cursorPaginate(500, cursor)
await searchIndex.upload(page.data.map((post) => post.toJSON()))
cursor = page.nextCursor ?? undefined
} while (cursor !== undefined)

See Pagination for how cursors stay correct while rows are being added.

“Property ‘map’ does not exist on type ‘Promise<Post[]>’”

Section titled ““Property ‘map’ does not exist on type ‘Promise<Post[]>’””
error TS2339: Property 'map' does not exist on type 'Promise<Post[]>'.

Why: the query returns a promise; the array only exists after it finishes.

Fix: await it first:

const titles = (await Post.query().get()).map((post) => post.title)
projects[0].budget + projects[1].budget // → '1200.50300.25', not 1500.75

Why: decimal columns are strings, so + joins them.

Fix: convert on purpose (Number(project.budget)), ideally to whole cents as shown above.

Loading a relationship inside map or a loop

Section titled “Loading a relationship inside map or a loop”
LazyLoadingError: You're loading "author" one "posts" row at a time (an N+1 query). Load it for the whole list instead: Model.query().with('author'), or await loadMany(models, 'author').

Fix: await loadMany(posts, 'author') before the loop, or add with('author') to the query.

JSON.stringify shows a getter’s value as missing

Section titled “JSON.stringify shows a getter’s value as missing”

Why: getters (accessors) like post.isPublished aren’t part of toJSON().

Fix: map to the shape you want: posts.map((post) => ({ ...post.toJSON(), isPublished: post.isPublished })), or use an API resource.