![\"Data](\"logo.svg\")
\n\n \n
@msw/dataData querying library for testing JavaScript applications.
\n\n## Motivation\n\nThis library exists to help developers model and query data when testing and developing their applications. It acts as a convenient way of creating schema-based fixtures and querying them with a familiar ORM-inspired syntax. It can be used standalone or in conjuncture with [Mock Service Worker](https://mswjs.io) for seamless mocking experience both on the network and the data layers.\n\n## Features\n\n- Relies on [Standard Schema][standard-schema] instead of inventing a proprietary modeling syntax you have to learn. You can use any Standard Schema-compliant object modeling library to describe your data, like Zod, ArkType, Valibot, yup, and many others.\n- Full runtime and type-safety.\n- Provides a powerful [querying syntax](#querying) (inspired by Prisma);\n- Supports [relations](#relations) for database-like behaviors (inspired by Drizzle);\n- Supports extensions (including custom extensions) for things like cross-tab collection synchronization or record persistence.\n\n---\n\n## Getting started\n\n### Install\n\n```\nnpm i @msw/data --save-dev\n```\n\n### Create collection\n\nYou start by defining a data _collection_.\n\n```ts\nimport { Collection } from '@msw/data'\nimport { z } from 'zod'\n\nconst users = new Collection({\n schema: z.object({\n id: z.number(),\n name: z.string(),\n }),\n})\n```\n\n> Above, I'm using [Zod](https://zod.dev/) to describe the `schema` for my users collection. You can use whichever [Standard Schema][standard-schema] compliant library of your choice instead.\n\n### Seed collection\n\nNext, let's put some values into our collection. Those values are called _records_ and you can create individual records via the `.create()` method or create a bunch of them with `.createMany()`.\n\n```ts\nawait users.create({ id: 1, name: 'John' })\n\nawait users.createMany(5, (index) => ({\n id: index + 1,\n name: faker.person.firstName(),\n}))\n```\n\n> Combine `.createMany()` with tools like [Faker](https://fakerjs.dev/) for random values in your records.\n\n### Use collection\n\nFrom this point on, you can use your `users` collection for anything data-related. You can create more records, query them, define relations to other collections, update and delete records, etc. Learn more you can do with the library in the documentation below. Good luck!\n\n---\n\n## Querying\n\n### Query syntax\n\nWhenever you have to target a record(s), you construct a _query_. A query acts as a predicate that a record must match in order to be targeted. The most basic query is that describing expected values of the record's properties:\n\n```ts\nusers.findFirst((q) => q.where({ name: 'John' }))\n```\n\n> Above, we are defining a query using the `q` builder that targets the first user whose `name` property equals to `'John'`.\n\nAdditionally, any property in a query can be expanded into a function that accepts the value and returns a boolean, indicating whether the record matches:\n\n```ts\nusers.findFirst((q) =>\n q.where({\n name: (name) => name.startsWith('John'),\n }),\n)\n```\n\n> This query matches the first user whose `name` starts with `'John'`. Use functions as predicates to express more advanced logic in your queries.\n\nQuery functions are supported at any level of nesting, including the top-level record itself.\n\n```ts\nusers.findFirst((q) => q.where((user) => user.posts.length > 0))\n\nusers.findFirst((q) =>\n q.where({\n address: {\n street: (street) => street !== 'Baker st.',\n },\n }),\n)\n```\n\n#### Logical operators\n\nYou can build complex queries via `.or()` and `.and()` logical operators exposed through the query builder. For example, here's a query that matches all users who have posts _or_ are editors:\n\n```ts\nusers.findMany((q) =>\n q.where({ posts: (posts) => posts.length > 0 }).or({ role: 'editor' }),\n)\n```\n\nIf you prefer functional composition over method chaining, you can wrap predicates in `q.or()` and `q.and()` instead. Both syntaxes result in the same query.\n\n```ts\nusers.findMany((q) =>\n q.or(\n q.where({ posts: (posts) => posts.length > 0 }),\n q.where({ role: 'editor' }),\n ),\n)\n```\n\n## Pagination\n\nThis library supports offset and cursor-based pagination.\n\n### Offset-based pagination\n\nProvide the `take` property onto the options object of any bulk operation method, like `.findMany()`, `.updateMany()`, or `.deleteMany()`, to limit the number of results returned by the query.\n\n```ts\nconst users = new Collection({ schema })\n\nusers.findMany(\n (q) => q.where({ email: (email) => email.includes('@google.com') }),\n {\n // Return the first 5 matching records.\n take: 5,\n },\n)\n```\n\nYou can also skip the number of first matching results by providing the `skip` property:\n\n```ts\nconst users = new Collection({ schema })\n\nusers.findMany(\n (q) => q.where({ email: (email) => email.includes('@google.com') }),\n {\n // Skip the first 10 matching records.\n skip: 10,\n // And return the next 5.\n take: 5,\n },\n)\n```\n\nThe negative value for `take` is also supported to have backward pagination:\n\n```ts\nusers.findMany(\n (q) => q.where({ email: (email) => email.includes('@google.com') }),\n {\n take: -5,\n },\n)\n````\n\n### Cursor-based pagination\n\nProvide a reference to the record of the same collection as the `cursor` property for cursor-based pagination.\n\n```ts\nconst users = new Collection({ schema })\n\nconst john = users.findFirst((q) => q.where({ name: 'John' }))\n\nusers.findMany((q) => q.where({ subscribed: true }), {\n cursor: john,\n take: 5,\n})\n```\n\n## Sorting\n\nYou can sort the results of bulk operations, like `.findMany()`, `.updateMany()`, and `.deleteMany()`, by providing the `orderBy` property in that operation's options.\n\n```ts\n// Find all users whose name starts with \"J\"\n// and return them sorted by their `name`.\nusers.findMany((q) => q.where({ name: (name) => name.startsWith('J') }), {\n orderBy: { name: 'asc' },\n})\n```\n\nYou can sort by multiple keys by listing them in the `orderBy` object:\n\n```ts\nusers.updateMany((q) => q.where({ name: (name) => name.startsWith('J') }), {\n data(user) {\n user.name = user.name.toUpperCase()\n },\n orderBy: {\n name: 'asc',\n id: 'desc',\n },\n})\n```\n\nYou can sort by an ordered list of criteria by passing an array to `orderBy`. Each entry is applied in sequence: the first entry determines the primary sort, and each subsequent entry breaks ties among records that compare equal under the preceding criteria.\n\n```ts\nusers.findMany(undefined, {\n orderBy: [{ age: 'asc' }, { name: 'desc' }]\n})\n```\n\n## Relations\n\nYou can define relations by calling the `.defineRelations()` method on the collection.\n\n- [One-to-one](#one-to-one)\n- [One-to-many](#one-to-many)\n- [One-to-many (inversed)](#one-to-many-inversed)\n- [Many-to-many](#many-to-many)\n- [Through relations](#through-relations)\n- [Unique relations](#unique-relations)\n- [Ambiguous relations](#ambiguous-relations)\n- [Polymorphic relations](#polymorphic-relations)\n\n### Defining relations\n\nBelow, you can find examples of defining various types of relations, but there are a few things that apply to all of them:\n\n- Describe relations on the schema level using your schema library. The `.defineRelations()` API has no effect on the model's schema/types and only operates on known properties;\n- Relations are described _after_ a collection is defined (to prevent circular references);\n- Relations do not require explicit `foreignKey` associations and instead are bound to internal IDs of related records.\n\n### One-to-one\n\n```ts\nconst userSchema = z.object({\n // In Zod, relational properties are best described as getters\n // so they can produce self-referencing schemas.\n get country() {\n return countrySchema\n },\n})\nconst countrySchema = z.object({ code: z.string() })\n\nconst users = new Collection({ schema: userSchema })\nconst countries = new Collection({ schema: countrySchema })\n\n// Declare the relations on the `users` collection.\nusers.defineRelations(({ one }) => ({\n // `user.country` is a one-of relation to the `countries` collection.\n country: one(countries),\n}))\n\nconst user = await users.create({\n country: await countries.create({ code: 'usa' }),\n})\nuser.country // { code: 'usa' }\n```\n\n### One-to-many\n\n```ts\nconst postSchema = z.object({\n get comments() {\n return z.array(countrySchema)\n },\n})\nconst commentSchema = z.object({\n text: z.string(),\n})\n\nconst posts = new Collection({ schema: postSchema })\nconst comments = new Collection({ schema: commentSchema })\n\nposts.defineRelations(({ many }) => ({\n comments: many(comments),\n}))\n\nawait posts.create({\n comments: [\n await comments.create({ text: 'First!' }),\n await comments.create({ text: 'Thanks for watching.' }),\n ],\n})\n```\n\n### One-to-many (inversed)\n\nTwo collections may self-reference each other. For example, `post.comments` is a list of comments while each `comment.post` references to the parent post.\n\n```ts\nconst postSchema = z.object({\n get comments() {\n return z.array(countrySchema)\n },\n})\nconst commentSchema = z.object({\n text: z.string(),\n get post() {\n return postSchema\n },\n})\n\nconst posts = new Collection({ schema: postSchema })\nconst comments = new Collection({ schema: commentSchema })\n\nposts.defineRelations(({ many }) => ({\n comments: many(comments),\n}))\ncomments.defineRelations(({ one }) => ({\n post: one(posts),\n}))\n\nawait posts.create({\n comments: [await comments.create({ text: 'First!' })],\n})\n\nconst comment = comments.findFirst((q) => q.where({ text: 'First!' }))\ncomment.post // { comments: [{ text: 'First', post: Circular }] }\n```\n\n> Inversed relations are updated automatically. Whenever you add a new comment to a post, both `post.comments` and `comment.post` are updated to reference each other. The same is true when setting a new parent `post` on the comment.\n\n### Many-to-many\n\nIn the next example, every `user` may have multiple `posts` while each `post` may have multiple `authors`.\n\n```ts\nconst userSchema = z.object({\n get posts() {\n return z.array(postSchemas)\n },\n})\nconst postSchema = z.object({\n get authors() {\n return z.array(userSchema)\n },\n})\n\nconst users = new Collection({ schema: userSchema })\nconst posts = new Collection({ schema: postSchema })\n\nusers.defineRelations(({ many }) => ({\n posts: many(posts),\n}))\nposts.defineRelations(({ many }) => ({\n authors: many(users),\n}))\n```\n\n### Through relations\n\nSince relational properties resolve via getters, there's no need to define special \"through\" relations to reference one model through a relation from another.\n\n```ts\nconst owners = new Collection({ schema: ownerSchema })\nconst cars = new Collection({ schema: carSchema })\nconst mechanics = new Collection({ schema: mechanicSchema })\n\nowners.defineRelations(({ many }) => ({\n cars: many(cars),\n}))\ncars.defineRelations(({ one }) => ({\n owner: one(owners),\n}))\nmechanics.defineRelations(({ one }) => ({\n car: one(cars),\n}))\n\nconst owner = await owners.create({ name: 'John' })\nconst car = await cars.create({ brand: 'bmw', owner })\nconst mechanic = await mechanics.create({ name: 'Kyle', car })\n\nmechanic.car.owner.name // \"John\"\n```\n\n> Note that although `mechanics` does not define an explicit relation to `owners`, you can get the owner of the car associated with a mechanic through the `car` relation.\n\n### Unique relations\n\nYou can mark a relation as unique by setting the `unique` property of the relation options to `true`. Unique relations cannot reference foreign records that are already associated with other owner records.\n\n```ts\nposts.defineRelations(({ one }) => ({\n author: one(users, { unique: true }),\n}))\n```\n\n> In this example, the `author` of each post points to a single _unique_ user. If a post attempts to set its author to a user that's already associated with another post, an error will be thrown.\n\n### Ambiguous relations\n\nYou can use the `role` option of the relation to disambiguate between multiple properties referencing the same foreign model.\n\nFor example, a single `post` may have both `author` and `reviewer` referencing the same `user` model. To make those properties pointing to _different_ user records, use the `role` that acts as a relation identifier. This way, the library will update the corresponding relational properties for both `users` and `posts` when the referenced relation is updated.\n\n```ts\nconst users = new Collection({ schema: userSchema })\nconst posts = new Collection({ schema: postSchema })\n\nusers.defineRelations(({ many }) => ({\n posts: many(posts, { role: 'author' }),\n reviews: many(posts, { role: 'reviewer' }),\n}))\n\nposts.defineRelations(({ one }) => ({\n author: one(user, { role: 'author' }),\n reviewer: one(user, { role: 'reviewer' }),\n}))\n```\n\n> The `role` property acts as a de-facto ID of a relation when synchronizing related models.\n\n### Polymorphic relations\n\nProvide an array of foreign collections to a relation to define it as _polymorphic_.\n\n```ts\nconst posts = new Collection({ schema: postSchema })\nconst images = new Collection({ schema: imageSchema })\nconst videos = new Collection({ schema: videoSchema })\n\nposts.defineRelations(({ many }) => ({\n // Providing a record of foreign collections allows\n // all of their records to be set as the value.\n attachments: many([images, videos]),\n}))\nimages.defineRelations(({ one }) => ({\n post: one(posts),\n}))\nvideos.defineRelations(({ one }) => ({\n post: one(posts),\n}))\n```\n\n> In this example, `post.attachments` is an array of either `images` or `videos`, where records from both collections are allowed.\n\n## Error handling\n\nData provides multiple different error classes to help you differentiate and handle different errors.\n\n### `OperationError`\n\n- `code` `