diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
index 5a7e990c..2eecbe82 100644
--- a/.github/FUNDING.yml
+++ b/.github/FUNDING.yml
@@ -1,2 +1,2 @@
github: mswjs
-open_collective: mswjs
+open_collective: mswjs
\ No newline at end of file
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1d46414e..3ca48c44 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -4,32 +4,37 @@ on:
push:
branches: [main]
pull_request:
- branches: [main]
-
workflow_dispatch:
jobs:
- build:
+ test:
runs-on: ubuntu-latest
steps:
- name: Checkout
- uses: actions/checkout@v2
+ uses: actions/checkout@v4
+
+ - name: Set up pnpm
+ uses: pnpm/action-setup@v4
+ with:
+ version: 9.15.0
+
+ - name: Set up Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: 24
+ cache: 'pnpm'
- name: Install dependencies
- run: yarn install --frozen-lockfile
+ run: pnpm install
- - name: Environment (versions)
- run: |
- echo "node: $(node -v)"
- echo "npm: $(npm -v)"
- echo "typescript: $(npm ls typescript)"
- echo "tsc: $(tsc -v)"
+ - name: Install browsers
+ run: pnpm exec playwright install chromium --with-deps
- name: Build
- run: yarn build
+ run: pnpm build
- - name: Tests
- run: yarn test
+ - name: Tests (Node.js)
+ run: pnpm test:node
- - name: Tests (typings)
- run: yarn test:ts
+ - name: Tests (browser)
+ run: pnpm test:browser
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 538cf671..f6bc65f7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -3,29 +3,55 @@ name: release
on:
schedule:
- cron: '0 23 * * *'
-
workflow_dispatch:
jobs:
- release:
+ publish:
runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ id-token: write
steps:
- name: Checkout
- uses: actions/checkout@v2
+ uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GH_ADMIN_TOKEN }}
- - name: Setup Git
+ - name: Set up pnpm
+ uses: pnpm/action-setup@v4
+ with:
+ version: 9.15.0
+
+ - name: Set up Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: 24
+ cache: 'pnpm'
+ always-auth: true
+ registry-url: https://registry.npmjs.org
+
+ - name: Set up Git
run: |
- git config --local user.name "kettanaito"
+ git config --local user.name "Artem Zakharchenko"
git config --local user.email "kettanaito@gmail.com"
- name: Install dependencies
- run: yarn install --frozen-lockfile
+ run: pnpm install
+
+ - name: Install browsers
+ run: pnpm exec playwright install chromium --with-deps
+
+ - name: Build
+ run: pnpm build
+
+ - name: Tests (Node.js)
+ run: pnpm test:node
+
+ - name: Tests (browser)
+ run: pnpm test:browser
- - name: Release
- run: yarn release
+ - name: Publish
+ run: pnpm release
env:
GITHUB_TOKEN: ${{ secrets.GH_ADMIN_TOKEN }}
- NPM_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/.gitignore b/.gitignore
index 611ff96e..6ad7ad0a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,7 @@
+*.DS_Store
node_modules
+build
lib
-*.log
\ No newline at end of file
+dist
+test-results
+./tests/.tmp/**
\ No newline at end of file
diff --git a/.node-version b/.node-version
new file mode 100644
index 00000000..54c65116
--- /dev/null
+++ b/.node-version
@@ -0,0 +1 @@
+v24
diff --git a/.prettierrc b/.prettierrc.json
similarity index 50%
rename from .prettierrc
rename to .prettierrc.json
index ba44425d..65854ba4 100644
--- a/.prettierrc
+++ b/.prettierrc.json
@@ -1,6 +1,6 @@
{
"semi": false,
- "singleQuote": true,
"arrowParens": "always",
- "trailingComma": "all"
+ "trailingComma": "all",
+ "singleQuote": true
}
diff --git a/.vscode/settings.json b/.vscode/settings.json
deleted file mode 100644
index 3662b370..00000000
--- a/.vscode/settings.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
- "typescript.tsdk": "node_modules/typescript/lib"
-}
\ No newline at end of file
diff --git a/LICENSE.md b/LICENSE.md
new file mode 100644
index 00000000..f1314ab0
--- /dev/null
+++ b/LICENSE.md
@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2020–present Artem Zakharchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/MIGRATING.md b/MIGRATING.md
new file mode 100644
index 00000000..d38da4cf
--- /dev/null
+++ b/MIGRATING.md
@@ -0,0 +1,148 @@
+# Migrating
+
+## v0 → v1
+
+Version 1.0 is a huge overhaul of the library to address some of the long-standing design issues and missing features. Please take your time to read through the [updated README](./README.md) to get familiar with the new concepts and APIs.
+
+When migrating from v0.x.x, please consult the guide below regarding the breaking changes to the library.
+
+### Terminology
+
+A few changes in the terminology to consider to make this migration guide easier to parse:
+
+- Model → Collection;
+- Entry → Record;
+- Relationship → Relation.
+
+### Package name
+
+The library has been migrated to a new package name—`@msw/data`.
+
+```diff
+-npm i @mswjs/data
++npm i @msw/data
+```
+
+### Deprecated: `factory`
+
+The model factory has been deprecated in favor of granular collections of data.
+
+```diff
+-const db = factory({ user: {} })
++const users = new Collection({ schema })
+```
+
+### Describing data
+
+The proprietary syntax of describing data has been deprecated in favor of the [Standard Schema](https://standardschema.dev/) for describing your data.
+
+```diff
+-factory({
+- firstName: () => 'John',
+- lastName: () => 'Maverick'
+-})
++new Collection({
++ schema: z.object({
++ firstName: z.string(),
++ lastName: z.string()
++ })
++})
+```
+
+> Although the example above is using [Zod](https://zod.dev/), you can use any Standard Schema-compatible schema library.
+
+### Deprecated: `primaryKey`
+
+The concept of a primary key has been deprecated entirely. You do not have to provide primary keys when describing your collections. You can query records by any properties.
+
+### Default values
+
+You can provide default values to the properties of your collection using the respective syntax of your schema library of choice. For example, here's how you list default values in Zod:
+
+```ts
+const users = new Collection({
+ schema: z.object({
+ subscribed: z.boolean().default(false)
+ })
+})
+
+await users.create() // { subscribed: false }
+```
+
+### Deprecated: `nullable`
+
+The `nullable` utility has been deprecated. Use your schema library of choice to describe nullable properties.
+
+### Deprecated: operators
+
+Operators like `equals`, `in`, `lgt`, etc. have been deprecated in favor of _queries_. You can express conditions for your records via literal values as well as function predicates.
+
+```ts
+// Find the first user with "id" equal to 1.
+users.findFirst(q => q.where({ id: 1 }))
+
+// Find all users whose last name is longer than 5 letters.
+users.findMany(
+ q => q.where({ lastName: lastName => lastName.length > 5 })
+)
+```
+
+> Learn more about [Querying](./README.md#querying).
+
+### Relations
+
+The `oneOf` and `manyOf` utilities has been deprecated. Use the `.defineRelations()` method on your collections to define relations between collections.
+
+```ts
+const userSchema = z.object({
+ id: z.number(),
+ get posts() {
+ return z.array(postSchema)
+ }
+})
+const postSchema = z.object({
+ title: z.string(),
+ get author() {
+ return userSchema
+ }
+})
+
+const users = new Collection({ schema: userSchema })
+const posts = new Collection({ schema: postSchema })
+
+users.defineRelations(({ many }) => ({
+ posts: many(posts)
+}))
+
+posts.defineRelations(({ one }) => ({
+ author: one(users)
+}))
+```
+
+> Learn more about [Relations](./README.md#relations).
+
+### Collocated updates
+
+You can now collocate updates of owner and foreign records in a relation by simply changing the foreign record's values as a part of the owner update.
+
+```ts
+const posts = new Collection({ schema: postSchema })
+const revisions = new Collection({ schema: revisionSchema })
+
+posts.defineRelations(({ one }) => ({
+ revision: one(revisions)
+}))
+
+await posts.update(q => q.where({ id: 'post-1' }), {
+ data(post) {
+ post.title = 'Renamed post'
+ post.revision.updatedAt = Date.now()
+ }
+})
+```
+
+> The library will automatically translte the `updateAt` change of the reference revision into an implicit update.
+
+### Deprecated: `.toHandlers()`
+
+The `.toHandlers()` method has been deprecated. Generating request handlers is no longer a responsibility of this library. Instead, it should be possible via [Source](https://github.com/mswjs/source) (follow [this issue](https://github.com/mswjs/source/issues/80) for progress).
diff --git a/README.md b/README.md
index cd5e5f23..d48770b9 100644
--- a/README.md
+++ b/README.md
@@ -1,1196 +1,848 @@
+[standard-schema]: https://standardschema.dev/
+
-
+@msw/dataData querying library for testing JavaScript applications.
-@mswjs/dataData modeling and relation library for testing JavaScript applications.
-(() => null),
- },
-})
+users.defineRelations(({ many }) => ({
+ posts: many(posts),
+}))
+posts.defineRelations(({ many }) => ({
+ authors: many(users),
+}))
```
-### Nested structures
+### Through relations
-You may use nested objects to design a complex structure of your model:
+Since relational properties resolve via getters, there's no need to define special "through" relations to reference one model through a relation from another.
-```js
-import { factory, primaryKey, nullable } from '@mswjs/data'
-
-const db = factory({
- user: {
- id: primaryKey(String),
- address: {
- billing: {
- street: String,
- city: nullable(String),
- },
- },
- },
-})
+```ts
+const owners = new Collection({ schema: ownerSchema })
+const cars = new Collection({ schema: carSchema })
+const mechanics = new Collection({ schema: mechanicSchema })
-// You can then create and query your data
-// based on the nested properties.
+owners.defineRelations(({ many }) => ({
+ cars: many(cars),
+}))
+cars.defineRelations(({ one }) => ({
+ owner: one(owners),
+}))
+mechanics.defineRelations(({ one }) => ({
+ car: one(cars),
+}))
-db.user.create({
- id: 'user-1',
- address: {
- billing: {
- street: 'Baker st.',
- city: 'London',
- },
- },
-})
+const owner = await owners.create({ name: 'John' })
+const car = await cars.create({ brand: 'bmw', owner })
+const mechanic = await mechanics.create({ name: 'Kyle', car })
-db.user.update({
- where: {
- id: {
- equals: 'user-1',
- },
- },
- data: {
- address: {
- billing: {
- street: 'Sunwell ave.',
- city: null,
- },
- },
- },
-})
+mechanic.car.owner.name // "John"
```
-> Note that you **cannot** mark a nested property as the [primary key](#using-the-primary-key).
+> 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.
-You may also specify _relationships_ nested deeply in your model:
+### Unique relations
-```js
-factory({
- user: {
- id: primaryKey(String),
- address: {
- billing: {
- country: oneOf('country'),
- },
- },
- },
- country: {
- code: primaryKey(String),
- },
-})
-```
+You 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.
-> Learn more about [Model relationships](#model-relationships).
-
-### Model relationships
+```ts
+posts.defineRelations(({ one }) => ({
+ author: one(users, { unique: true }),
+}))
+```
-- [One-to-One](#one-to-one)
-- [One-to-Many](#one-to-many)
-- [Many-to-One](#many-to-one)
-- [Unique relationships](#unique-relationships)
-- [Nullable relationships](#nullable-relationships)
+> 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.
-Relationship is a way for a model to reference another model.
+### Ambiguous relations
-#### One-to-One
+You can use the `role` option of the relation to disambiguate between multiple properties referencing the same foreign model.
-```js
-import { factory, primaryKey, oneOf } from '@mswjs/data'
+For 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.
-const db = factory({
- user: {
- id: primaryKey(String),
- firstName: String,
- },
- post: {
- id: primaryKey(String),
- title: String,
- // The "post.author" references a "user" model.
- author: oneOf('user'),
- },
-})
+```ts
+const users = new Collection({ schema: userSchema })
+const posts = new Collection({ schema: postSchema })
-const user = db.user.create({ firstName: 'John' })
-const post = db.post.create({
- title: 'My journey',
- // Use a "user" entity as the actual value of this post's author.
- author: user,
-})
+users.defineRelations(({ many }) => ({
+ posts: many(posts, { role: 'author' }),
+ reviews: many(posts, { role: 'reviewer' }),
+}))
-post.author.firstName // "John"
+posts.defineRelations(({ one }) => ({
+ author: one(user, { role: 'author' }),
+ reviewer: one(user, { role: 'reviewer' }),
+}))
```
-#### One-to-Many
-
-```js
-import { factory, primaryKey, manyOf } from '@mswjs/data'
+> The `role` property acts as a de-facto ID of a relation when synchronizing related models.
-const db = factory({
- user: {
- id: primaryKey(String),
- // "user.posts" is a list of the "post" entities.
- posts: manyOf('post'),
- },
- post: {
- id: primaryKey(String),
- title: String,
- },
-})
+### Polymorphic relations
-const posts = [
- db.post.create({ title: 'First' }),
- db.post.create({ title: 'Second' }),
-]
+Provide an array of foreign collections to a relation to define it as _polymorphic_.
-const user = db.user.create({
- // Assign the list of existing posts to this user.
- posts,
-})
+```ts
+const posts = new Collection({ schema: postSchema })
+const images = new Collection({ schema: imageSchema })
+const videos = new Collection({ schema: videoSchema })
-user.posts // [{ title: "First" }, { title: "Second" }]
+posts.defineRelations(({ many }) => ({
+ // Providing a record of foreign collections allows
+ // all of their records to be set as the value.
+ attachments: many([images, videos]),
+}))
+images.defineRelations(({ one }) => ({
+ post: one(posts),
+}))
+videos.defineRelations(({ one }) => ({
+ post: one(posts),
+}))
```
-#### Many-to-One
+> In this example, `post.attachments` is an array of either `images` or `videos`, where records from both collections are allowed.
-```js
-import { factory, primaryKey, oneOf } from '@mswjs/data'
+## Error handling
-const db = factory({
- country: {
- name: primaryKey(String),
- },
- user: {
- id: primaryKey(String),
- country: oneOf('country'),
- },
- car: {
- serialNumber: primaryKey(String),
- country: oneOf('country'),
- },
-})
+Data provides multiple different error classes to help you differentiate and handle different errors.
-const usa = db.country.create({ name: 'The United States of America' })
+### `OperationError`
-// Create a "user" and a "car" with the same country.
-db.user.create({ country: usa })
-db.car.create({ country: usa })
-```
+- `code` ``, the error code describing the failed operation;
+- `cause` `` (_optional_), a reference to the original thrown error.
-#### Unique relationships
+Thrown whenever performing a record operation fails. For example:
-Both `oneOf` and `manyOf` relationships may be marked as unique. A unique relationship is where a referenced entity cannot be assigned to another entity more than once.
+- When creating a new record whose initial values do not match the collection's schema;
+- When there are no records found for a strict query.
-In the example below we define the "user" and "invitation" models, and design their relationship so that one invitation cannot be assigned to multiple users.
+### `RelationError`
-```js
-import { factory, primaryKey, oneOf } from '@mswjs/data'
+- `code` ``, the error code describing the relation operation;
+- `info` ``, additional error information;
+ - `path` ``, path of the relational property;
+ - `ownerCollection` ``, a reference to the owner collection;
+ - `foreignCollection` `>`, an array of foreign collections referenced by this relation;
+ - `options` `RelationDefinitionOptions`, the options object passed upon decaring this relation.
-const db = factory({
- user: {
- id: primaryKey(String),
- invitation: oneOf('invitation', { unique: true }),
- },
- invitation: {
- id: primaryKey(String),
- },
-})
+Thrown whenever performing a relation operation fails. For example:
-const invitation = db.invitation.create()
+- When attempting to reference a foreign record that's already associated with another record in a unique relation;
+- When directly assigning value to a relational property.
-const john = db.user.create({ invitation })
+---
-// Assigning the invitation already used by "john"
-// will throw an exception when creating this entity.
-const karl = db.user.create({ invitation })
-```
+## API
-#### Nullable relationships
+### `new Collection(options)`
-Both `oneOf` and `manyOf` relationships may be passed to `nullable` to allow
-instantiating and updating that relation to null.
+- `options` ``
+ - `schema` [Standard Schema][standard-schema] A schema describing each record in this collection.
+ - `extensions` (optional) An array of [extensions](#extensions) to use on this collection.
-```js
-import { factory, primaryKey, oneOf, nullable } from '@mswjs/data'
+Creates a new collection of data.
-const db = factory({
- user: {
- id: primaryKey(String),
- invitation: nullable(oneOf('invitation')),
- friends: nullable(manyOf('user')),
- },
- invitation: {
- id: primaryKey(String),
- },
-})
+#### `.create(initialValues)`
-const invitation = db.invitation.create()
+- `initialValues` Initial values for the new record.
-// Nullable relationships are instantiated with null.
-const john = db.user.create({ invitation }) // john.friends === null
-const kate = db.user.create({ friends: [john] }) // kate.invitation === null
+Creates a single record with the provided initial values.
-db.user.updateMany({
- where: {
- id: {
- in: [john.id, kate.id],
- },
- },
- data: {
- // Nullable relationships can be updated to null.
- invitation: null,
- friends: null,
- },
-})
+```ts
+const user = await users.create({ id: 1, name: 'John' })
```
-### Querying data
-
-This library supports querying of the seeded data similar to how one would query a SQL database. The data is queried based on its properties. A query you construct depends on the value type you are querying.
+> The `.create()` method returns a promise to support potential asynchronous transformations in your schema.
-#### String operators
+#### `.createMany(count, initialValuesFactory)`
-- `equals`
-- `notEquals`
-- `contains`
-- `notContains`
-- `in`
-- `notIn`
+- `count` `` A number of records to create.
+- `initialValuesFactory` `` A function that returns initial values for each record.
-#### Number operators
+Creates multiple records with the initial value factory.
-- `equals`
-- `notEquals`
-- `gt`
-- `gte`
-- `lt`
-- `lte`
-- `between`
-- `notBetween`
-- `in`
-- `notIn`
-
-#### Boolean operators
+```ts
+const users = await users.createMany(5, (index) => ({
+ id: index + 1,
+ name: 'John',
+}))
+```
-- `equals`
-- `notEquals`
+The initial value factory function accepts the `index` argument indicating the index of the record that's being created. Use it, as well as the function's closure, to generate unique or random values.
-#### Date operators
+#### `.findFirst(query)`
-- `equals`
-- `notEquals`
-- `gt`
-- `gte`
-- `lt`
-- `lte`
+- `query` [`Query`](#new-querypredicate) A query matching the record.
-#### Query example
+Returns the first record matching the query.
-```js
-const db = factory({
- post: {
- id: String,
- likes: Number,
- isDraft: Boolean,
- },
+```ts
+const users = new Collection({
+ schema: z.object({
+ id: z.number(),
+ name: z.string(),
+ }),
})
-// Returns the list of `post` entities
-// that satisfy the given query.
-const popularPosts = db.post.findMany({
- where: {
- likes: {
- gte: 1000,
- },
- isDraft: {
- equals: false,
- },
- },
-})
+await users.create({ id: 1, name: 'John' })
+await users.create({ id: 2, name: 'John' })
+
+users.findFirst((q) => q.where({ name: 'John' }))
+// { id: 1, name: 'John' }
```
-### Strict mode
+#### `.findMany(query)`
-When querying or updating the entities you can supply the `strict: boolean` property on the query. When supplied, if a query operation fails (i.e. no entity found), the library will throw an exception.
+- `query` [`Query`](#new-querypredicate) A query matching the records.
-```js
-import { factory, primaryKey } from '@mswjs/data'
+Returns all records matching the query.
-const db = factory({
- user: {
- id: primaryKey(String),
- },
+```ts
+const users = new Collection({
+ schema: z.object({
+ id: z.number(),
+ name: z.string(),
+ }),
})
-db.user.create({ id: 'abc-123' })
+await users.create({ id: 1, name: 'John' })
+await users.create({ id: 2, name: 'John' })
-// This will throw an exception, because there are
-// no "user" entities matching this query.
-db.user.findFirst({
- where: {
- id: {
- equals: 'def-456',
- },
- },
- strict: true,
-})
+users.findMany((q) => q.where({ name: 'John' }))
+// [{ id: 1, name: 'John' }, { id: 2, name: 'John' }]
```
-### Pagination
+#### `.update(query, options)`
-This library supports _offset-based_ and _cursor-based_ pagination of the `findMany` method results.
+- `query` [`Query`](#new-querypredicate) A query matching the record.
+- `options` ``
+ - `data` A function that produces changes by modifying the previous record.
-#### Offset-based pagination
+Updates the first record matching the query. Returns a promise that resolves with the updated record.
-```js
-const db = factory({
- post: {
- id: primaryKey(String),
- category: String,
- },
-})
-
-db.post.findMany({
- where: {
- category: {
- equals: 'Science',
- },
+```ts
+// Change the name for the user with a specific `id`.
+const updatedUser = await users.update((q) => q.where({ id: 123 }), {
+ data(user) {
+ user.name = 'Johnatan'
},
- take: 15,
- skip: 10,
})
```
-#### Cursor-based pagination
+> Update methods return a promise in order to support potential asynchronous transformations defined in your schema.
-The `cursor` option of the `findMany` query expects a primary key value of a model to start the pagination from.
+The `data` function allows you to perform multiple updates upon a record by mutating that record directly. Think of it as a draft function from libraries like `immer` or `mutative` because that's precisely what it is!
-```js
-const db = factory({
- post: {
- // The `id` primary key will be used as a cursor.
- id: primaryKey(String),
- category: String,
- },
-})
+You can also provide a record reference as the predicate to the `.update()` method to update that particular record:
-const firstPage = db.post.findMany({
- where: {
- category: {
- equals: 'Science',
- },
- },
- take: 15,
- cursor: null,
-})
-
-const secondPage = db.post.findMany({
- where: {
- category: {
- equals: 'Science',
- },
+```ts
+const user = users.findFirst((q) => q.where({ id: 123 }))
+await users.update(user, {
+ // 👆👆
+ data(user) {
+ user.id = 456
},
- take: 15,
- // The second page will start from the last post
- // of the `firstPage`.
- cursor: firstPage[firstPage.length - 1].id,
})
```
-### Sorting
+#### `.updateMany(query, options)`
-#### Basic sorting
+- `query` [`Query`](#new-querypredicate) A query matching the records.
+- `options` ``
+ - `data` Changes to apply to each record.
-```js
-const db = factory({
- post: {
- id: primaryKey(String),
- title: String,
- },
-})
+Updates all records matching the query. Returns a promise that resolves with an array containing the updated records.
-// Return first 10 posts in the "Science" category
-// sorted by the post's "title".
-db.post.findMany({
- where: {
- category: {
- equals: 'Science',
- },
- },
- take: 10,
- orderBy: {
- title: 'asc',
+```ts
+// Find all the users with the name "John"
+// and make their name truly stand out!
+const updatedUsers = await users.updateMany((q) => q.where({ name: 'John' }), {
+ data(user) {
+ user.name = user.name.toUpperCase()
},
})
```
-> You can use `orderBy` with [pagination](#pagination).
+#### `.delete(query)`
-#### Sorting by relational properties
+- `query` [`Query`](#new-querypredicate) A query matching the record.
-```js
-const db = factory({
- post: {
- id: primaryKey(String),
- title: String,
- author: oneOf('user'),
- },
- user: {
- id: primaryKey(String),
- firstName: String,
- },
-})
+Deletes the first record matching the query. Returns the deleted record.
-// Return all posts in the "Science" category
-// sorted by the post author's first name.
-db.post.findMany({
- where: {
- category: {
- equals: 'Science',
- },
- },
- orderBy: {
- author: {
- firstName: 'asc',
- },
- },
-})
+```ts
+// Delete a user with a particular `id`.
+const deletedUser = users.delete((q) => q.where({ id: 123 }))
```
-#### Sorting by multiple criteria
-
-Provide a list of criteria to sort the query result against.
+You can also provide a record reference as the predicate to the `.delete()` method to delete that particular record:
-```js
-db.post.findMany({
- orderBy: [
- {
- title: 'asc',
- },
- {
- views: 'desc',
- },
- ],
-})
+```ts
+const user = users.findFirst((q) => q.where({ id: 123 }))
+users.delete(user)
```
-You can also use a combination of direct and relational properties on a single query:
+#### `.deleteMany(query)`
-```js
-db.post.findMany({
- orderBy: [
- {
- title: 'asc',
- },
- {
- author: {
- firstName: 'asc',
- },
- },
- ],
-})
-```
+- `query` [`Query`](#new-querypredicate) A query matching the records.
-### Database utilities
+Deletes all records matching the query. Returns an array containing the deleted records.
-#### `drop`
+```ts
+// Delete all users whose trial period has expired.
+const deletedUsers = users.deleteMany((q) =>
+ q.where({ trial: { expiresAt: (expiresAt) => expiresAt <= Date.now() } }),
+)
+```
-Drops the given database, deleting all its entities.
+#### `.defineRelations(definition)`
-```js
-import { factory, drop } from '@mswjs/data'
+- `definition` `` A function that accepts relation utilities and returns an object with relational properties.
-const db = factory({...})
+Defines relations on the current collection.
-drop(db)
-```
+```ts
+const users = new Collection({ schema: userSchema })
+const posts = new Collection({ schema: postSchema })
-### Usage with `Faker`
+users.defineRelations(({ many }) => ({
+ // `user.posts` is a many-of relation to `posts`.
+ posts: many(posts)
+}))
+```
-Libraries like [Faker](https://github.com/faker-js/faker) can help you generate fake data for your models.
+> You can define nested relational properties by nesting them in the object returned from `.defineRelations()`.
-```js
-import { seed, datatype, name } from '@faker-js/faker'
-import { factory, primaryKey } from '@mswjs/data'
+##### Relational utilities
-// (Optional) Seed `faker` to ensure reproducible
-// random values of model properties.
-seed(123)
+The following relational utilities are exposed in the argument to this method:
-factory({
- user: {
- id: primaryKey(datatype.uuid),
- firstName: name.firstName,
- },
-})
-```
+- `one(collection[, options])`, defines a one-of relation to the given collection;
+- `many(collection[, options])`, defines a many-of relation to the given collection.
-### Collocated updates
+##### Relation options
-When you wish to update a parent entity and one of its relational properties at the same time, collocate such an update operation via the updater function of the [`update`](#update) method.
+- `unique` ``, marks this relation as unique. Foreign records referenced by this relation cannot be referenced by other models.
-```js
-import { factory, primaryKey, oneOf } from '@mswjs/data'
+```ts
+users.defineRelations(({ many }) => ({
+ posts: many(posts)
+}))
+posts.defineRelations(({ one }) => ({
+ author: one(users, { unique: true })
+}))
-const db = factory({
- post: {
- id: primaryKey(String),
- title: String,
- revision: oneOf('revision'),
- },
- revision: {
- id: primaryKey(String),
- updatedAt: () => new Date(),
- },
+const john = await users.create({
+ name: 'John',
+ // `john` is associated as the `author` of this post now.
+ posts: [await posts.create({ title: 'First post' })]
})
-db.post.update({
- where: {
- id: { equals: 'post-1' },
- },
- data: {
- title: 'Renamed post',
- // The next value of the "post.revision"
- // is returned from this updater function.
- revision(prevRevision, post) {
- // Update this post's revision as you'd do usually,
- // but nested within the post's update operation.
- return db.revision.update({
- where: {
- id: { equals: post.revision.id },
- },
- data: {
- updatedAt: Date.now(),
- },
- })
- },
- },
+await users.create({
+ name: 'Katy',
+ // Creating this user will error because it tries to list
+ // a post which `author` already references to another user.
+ posts: [john.posts[0]]
})
```
-> While the `post` above will get updated, both `post.revision` and the respective `revision` standalone will be updated as well.
+- `role` ``, an identifier to differentiate ambiguous relations to the same foreign collection;
-Collocating nested updates grants you a predictable behavior when changing multiple related entities.
+```ts
+users.defineRelations(({ many }) => ({
+ // Both `users` and `posts` reference each other in multiple keys.
+ // Using `role` helps the library understand which keys are connected.
+ posts: many(posts, { role: 'author' }),
+ underReview: many(posts, { role: 'reviewer' })
+}))
-## Usage with API mocks
+posts.defineRelations(({ one, many }) => ({
+ author: one(users, { role: 'author' }),
+ reviewers: many(users, { role: 'reviewer' })
+}))
+```
-While this library can be used standalone, it brings a tremendous benefit in a combination with tools like [Mock Service Worker](https://github.com/mswjs). We provide a build-in API to quickly generate API request handlers based on your models, representing model interactions via HTTP requests.
+- `onDelete` `"cascade" | undefined`, decides how to handle referenced foreign records when the owner is deleted.
-### Generate request handlers
+```ts
+users.defineRelations(({ many }) => ({
+ // If a user gets deleted, delete all of the `posts` associated with them.
+ posts: many(posts, { onDelete: 'cascade' })
+}))
+posts.defineRelations(({ one }) => ({
+ author: one(users)
+}))
+```
-Both REST and GraphQL [request handlers]() can be generated from a model using the [`.toHandlers()`](#toHandlers) method of that model. When generated, request handlers automatically have that model's CRUD methods like `POST /user` or `mutation CreateUser`.
+### `new Query([predicate])`
-#### Generate REST API
+- `predicate` (optional) An object or a function that acts as a predicate for records.
-REST API request handlers can be generated by calling the `.toHandlers('rest')` method on the respective factory model.
+Creates a new query to match records in a collection. Normally, you query records through the querying methods of the collection (see [Querying](#querying)). You can, however, construct a type-safe `Query` class to abstract common queries or query builders.
```ts
-import { setupServer } from 'msw/node'
-import { factory, primaryKey } from '@mswjs/data'
-
-const db = factory({
- user: {
- id: primaryKey(String),
- firstName: String,
- },
+const userSchema = z.object({
+ id: z.number(),
+ subscribed: z.boolean().default(false),
+ role: z.enum(['user', 'editor', 'admin']).default('user'),
})
-const handlers = [...db.user.toHandlers('rest')]
-
-// Establish requests interception.
-const server = setupServer(...handlers)
-server.listen()
+// Creates a query builder for the users schema.
+const query = new Query()
```
-Given the "user" model definition above, the following request handlers are generated and connected to the respective database operations:
+#### `.where(predicate)`
-- `GET /users/:id` (where "id" is your model's primary key), returns a user by ID;
-- `GET /users`, returns all users (supports [pagination](#pagination));
-- `POST /users`, creates a new user;
-- `PUT /users/:id`, updates an existing user by ID;
-- `DELETE /users/:id`, deletes an existing user by ID;
+- `predicate` A predicate for the records.
+- Returns: [`Query`](#new-querypredicate).
-The "/user" part of the route is derived from your model name. For example, if you had a "post" model defined in your `factory`, then the generated handlers would be `/posts`, `/posts/:id`, etc.
+```ts
+query.where({ id: 2 })
+```
-With the request handlers generated and MSW configured, you can query the "database" using REST API:
+#### `.or(predicate)`
-```js
-// Create a new user in the database.
-fetch('/users', {
- method: 'POST',
- headers: {
- 'Content-Type': 'application/json',
- },
- body: JSON.stringify({
- id: 'abc-123',
- firstName: 'John',
- }),
-})
+- `predicate` A predicate or another [`Query`](#new-querypredicate).
+- Returns: [`Query`](#new-querypredicate).
+
+Creates a new query, merging the previous predicates with the new one under a `OR` relation. A record may match _any predicate_ to be considered matching.
+
+```ts
+const unsubscribedOrEditorsQuery = query.or(
+ query.where({ subscribed: false }),
+ query.where({ role: 'editor' }),
+)
```
-#### Generate GraphQL API
+#### `.and(predicate)`
-GraphQL API request handlers can be generated by calling the `.toHandlers('graphql')` method on the respective factory model.
+- `predicate` A predicate or another [`Query`](#new-querypredicate).
+- Returns: [`Query`](#new-querypredicate).
-```js
-import { setupServer } from 'msw/node'
-import { factory, primaryKey } from '@mswjs/data'
+Creates a new query, merging the previous predicates with the new one under a `AND` relation. A record must match _all predicates_ to be considered matching.
-const db = factory({
- user: {
- id: primaryKey(String),
- firstName: String,
- },
-})
+```ts
+const exactAdminQuery = query.and(
+ query.where({ id: 1 }),
+ query.where({ role: 'admin' }),
+)
+```
-const handlers = [...db.user.toHandlers('graphql')]
+#### `.test(record)`
-// Establish requests interception.
-const server = setupServer(...handlers)
-server.listen()
+- `record` `` A reference to a record to test.
+- Returns `` Indicates whether the given record matches the query.
+
+```ts
+query.test({ id: 1 })
```
-Given the "user" model definition above, the following request handlers are generated and connected to the respective database operations:
+---
-- `user(where: UserQueryInput): User`, returns a user matching the query;
-- `users(where: UserQueryInput, cursor: ID, skip: Int, take: Int): [User!]`, returns all users matching the query (supports [pagination](#pagination));
-- `createUser(data: UserInput!): User!`, creates a new user;
-- `updateUser(where: UserQueryInput!, data: UserInput!): User!`, updates a user that match the `where` query;
-- `updateUsers(where: UserQueryInput!, data: UserInput!): [User!]`, updates multiple users that match the `where` query;
-- `deleteUser(where: UserQueryInput!): User!`, deletes a user that match the `where` query;
-- `deleteUsers(where: UserQueryInput!): [User!]`, deletes multiple users that match the `where` query.
+## Extensions
-The "User" part of the GraphQL operation names is derived from your model's name. For example, if you had a "post" model defined in your `factory`, then the generated handlers would have operations like `post`, `createPost`, `updatePosts`, etc.
+You can extend the behavior of collections via _extensions_. The library comes with the following default extensions, but you can always [create your own](#custom-extensions).
-With the request handlers generated and MSW configured, you can query the database using GraphQL API:
+### Default extensions
-```js
-import { gql, useQuery } from '@apollo/client'
+#### `sync()`
-const CREATE_USER = gql`
- query CreateUser($initialValues: UserInput!) {
- createUser(data: $initialValues) {
- firstName
- }
- }
-`
+> [!WARNING]
+> The `sync()` extension is browser-only. It will be ignored in Node.js.
-useQuery(CREATE_USER, {
- variables: {
- initialValues: {
- firstName: 'John',
- },
- },
+Synchronizes collection changes, like creating/updating/deleting records, with the same collection in another browser tab via a `BroadcastChannel`.
+
+```ts
+import { Collection } from '@msw/data'
+import { sync } from '@msw/data/extensions/sync'
+
+const users = new Collection({
+ schema,
+ extensions: [sync()],
})
```
-### Manual integration
+#### `persist()`
-To gain more control over the mocks and implement more complex mocking scenarios (like authentication), consider manual integration of this library with your API mocking solution.
+> [!WARNING]
+> The `persist()` extension is browser-only. It will be ignored in Node.js.
-Take a look at how you can create an entity based on the user's authentication status in a test:
+Persist the records in the collection between page reloads.
-```js
-import { rest } from 'msw'
-import { setupServer } from 'msw/node'
-import { factory, primaryKey } from '@mswjs/data'
+```ts
+import { Collection } from '@msw/data'
+import { persist } from '@msw/data/extensions/persist'
-const db = factory({
- post: {
- id: primaryKey(String),
- title: String,
- },
+const users = new Collection({
+ schema,
+ extensions: [persist()],
})
+```
-const handlers = [
- rest.post('/post', (req, res, cxt) => {
- // Only authenticated users can create new posts.
- if (req.headers.get('authorization') === 'Bearer AUTH_TOKEN') {
- return res(ctx.status(403))
- }
-
- // Create a new entity for the "post" model.
- const newPost = db.post.create(req.body)
-
- // Respond with a mocked response.
- return res(ctx.status(201), ctx.json({ post: newPost }))
- }),
-]
+### Custom extensions
-// Establish requests interception.
-const server = setupServer(...handlers)
-server.listen()
+```ts
+// my-extension.ts
+import { defineExtension } from '@msw/data/extensions'
+
+export function myExtension() {
+ return defineExtension({
+ name: 'my-extension',
+ extend(collection) {
+ // Your logic here.
+ },
+ })
+}
```
-## Honorable mentions
+```ts
+import { Collection } from '@msw/data'
+import { myExtension } from './my-extension.js'
-- [Prisma](https://www.prisma.io) for inspiring the querying client.
-- [Lenz Weber](https://twitter.com/phry) and [Matt Sutkowski](https://twitter.com/de_stroy) for great help with the TypeScript support.
+new Collection({ schema, extensions: [myExtension()] })
+```
diff --git a/commitlint.config.js b/commitlint.config.js
deleted file mode 100644
index 98ee7dfc..00000000
--- a/commitlint.config.js
+++ /dev/null
@@ -1,3 +0,0 @@
-module.exports = {
- extends: ['@commitlint/config-conventional'],
-}
diff --git a/decisions/primary-key.md b/decisions/primary-key.md
new file mode 100644
index 00000000..4cebc418
--- /dev/null
+++ b/decisions/primary-key.md
@@ -0,0 +1,3 @@
+# Primary key
+
+The `primaryKey()` function has been abolished in favor of internal record ID. Every record gets assigned a random immutable UUID upon its creation. The library uses those internal IDs primarily for associating records with each other in relations. The user is free to treat any of the defined model properties as a "primary key", but no such functionality longer exists in the library.
diff --git a/decisions/query-syntax.md b/decisions/query-syntax.md
new file mode 100644
index 00000000..459109a6
--- /dev/null
+++ b/decisions/query-syntax.md
@@ -0,0 +1,52 @@
+# Query syntax
+
+## Query methods
+
+Query methods like `.findFirst()`, `.findMany()`, `.update()`, `.updateMany()`, and others were chosen due to developer familiarity as they might find those (or similar) methods in ORM libraries, like Prisma or Drizzle. I personally like create-find-update-delete terminology.
+
+## Query builder
+
+I went with the query builder pattern over something like `{ OR, AND }` key syntax you might find in Prisma because I dislike mixing record properties and logical properties.
+
+```ts
+users.findFirst({
+ where: {
+ OR: [{ id: 2 }, { name: 'Bob', AND: [{ subscribed: true }] }],
+ },
+})
+```
+
+Mixing record properties and logical properties results in queries that are hard to read. Compare this to the builder syntax that wraps predicates in logical expressions instead:
+
+```ts
+users.findFirst((q) =>
+ q.where({ id: 2 }).or(q.where({ name: 'Bob', subscribed: true })),
+)
+```
+
+Query predicates always include only the record properties, which makes them easy to write. They can be abstracted and composed in any arrangement of logical `q.or` or `q.and` sequences. This composition also allows for mix-and-matching of syntax with zero additional handling on the library's side:
+
+```ts
+users.findFirst((q) => q.or(q.where({ id: 2 }), q.where({ name: 'Bob' })))
+```
+
+## Convenience keys
+
+Convenience keys like `equals`, `in`, `lg`, `notContains`, and others were dropped in favor of function predicates. Functions are infinitely more powerful and the internal overhead of differentiating between reserved convenience keys and user-provided keys is not worth whatever little brevity gained as a result.
+
+You can describe custom logic in your query predicates since any field (or the entire record) can be described as a function.
+
+```ts
+users.findFirst((q) =>
+ q.where({
+ id: (id) => isList.includes(id), // vs { in: idList }
+ }),
+)
+
+users.findFirst((q) =>
+ q.where((user) => {
+ // Custom predicate accepting the entire record.
+ return hasRole('admin', user)
+ }),
+)
+```
diff --git a/decisions/standard-schema.md b/decisions/standard-schema.md
new file mode 100644
index 00000000..c879cc3e
--- /dev/null
+++ b/decisions/standard-schema.md
@@ -0,0 +1,39 @@
+# Standard Schema
+
+I chose to adopt [Standard Schema](https://standardschema.dev/) as the way to define models. This library was never meant to have a custom modeling syntax you have to learn. With the introduction of Standard Schema, it can now rely on any standard-compliant modeling library as the input, making it easier for developers to adopt.
+
+```ts
+import { Collection } from '@msw/data'
+import { z } from 'zod'
+
+const users = new Collection({
+ schema: z.object({
+ id: z.number(),
+ name: z.string().optional(),
+ }),
+})
+```
+
+> Above, Zod is used to model the `users` collection. You can use any of the Standard Schema-compatible libraries instead.
+
+This decision also allows the library to offload custom features, like derived properties, to the schema libraries. For example, to derive a model's property from another property, you follow your schema library's best practices.
+
+```ts
+new Collection({
+ schema: z
+ .object({
+ name: z.string(),
+ email: z.email(),
+ })
+ .transform((user) => {
+ user.email = `${user.name.toLowerCase()}@email.com`
+ return user
+ }),
+})
+```
+
+> Above, I'm using Zod's `.transform()` method to derive the `email` field from the `name` field.
+
+## Model restrictions
+
+In order to support internal IDs and relations, user-defined models _must be either objects or arrays_.
diff --git a/extensions/package.json b/extensions/package.json
new file mode 100644
index 00000000..b855b3a4
--- /dev/null
+++ b/extensions/package.json
@@ -0,0 +1,15 @@
+{
+ "type": "module",
+ "main": "./../build/extensions/index.js",
+ "types": "./../build/extensions/index.d.ts",
+ "exports": {
+ "./sync": {
+ "types": "./../build/extensions/sync.d.ts",
+ "default": "./../build/extensions/sync.js"
+ },
+ "./persist": {
+ "types": "./../build/extensions/persist.d.ts",
+ "default": "./../build/extensions/persist.js"
+ }
+ }
+}
diff --git a/logo.svg b/logo.svg
index f66e60e3..30f32b6d 100644
--- a/logo.svg
+++ b/logo.svg
@@ -26,4 +26,4 @@
-
\ No newline at end of file
+
diff --git a/ossjs.release.config.js b/ossjs.release.config.js
deleted file mode 100644
index 3f582643..00000000
--- a/ossjs.release.config.js
+++ /dev/null
@@ -1,3 +0,0 @@
-module.exports = {
- script: 'yarn publish --new-version $RELEASE_VERSION',
-}
diff --git a/package.json b/package.json
index 71d90cfb..8968c5ef 100644
--- a/package.json
+++ b/package.json
@@ -1,69 +1,63 @@
{
- "name": "@mswjs/data",
- "description": "Data modeling and relation library for testing JavaScript applications.",
- "version": "0.10.1",
- "main": "lib/index.js",
- "typings": "lib/index.d.ts",
- "author": "Artem Zakharchenko",
- "license": "MIT",
+ "type": "module",
+ "name": "@msw/data",
+ "version": "1.1.7",
+ "description": "Data querying library for testing JavaScript applications.",
"scripts": {
- "start": "tsc -w",
- "format": "prettier src/**/*.ts --write",
- "test": "jest -c test/jest.config.ts",
- "test:ts": "tsc -p test/tsconfig.test-d.json",
- "clean": "rimraf ./lib",
- "build": "yarn clean && tsc",
- "release": "release publish",
- "prepare": "yarn simple-git-hooks init",
- "prepublishOnly": "yarn build && yarn test:ts && yarn test"
+ "dev": "tsdown -w",
+ "test:node": "vitest",
+ "test:browser": "playwright test",
+ "lint": "publint",
+ "build": "tsdown",
+ "release": "release publish"
+ },
+ "imports": {
+ "#/src/*": "./src/*"
+ },
+ "exports": {
+ ".": "./build/index.mjs",
+ "./extensions": "./build/extensions/index.mjs",
+ "./extensions/sync": "./build/extensions/sync.mjs",
+ "./extensions/persist": "./build/extensions/persist.mjs"
},
"files": [
- "lib",
- "README.md"
+ "./build",
+ "./src",
+ "./tests"
+ ],
+ "keywords": [
+ "data",
+ "query",
+ "mock",
+ "model",
+ "testing",
+ "fake",
+ "msw"
],
+ "license": "MIT",
+ "author": "Artem Zakharchenko ",
+ "homepage": "https://github.com/mswjs/data",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/mswjs/data.git"
+ },
"devDependencies": {
- "@commitlint/cli": "^16.0.1",
- "@commitlint/config-conventional": "^16.0.0",
- "@ossjs/release": "^0.2.1",
- "@types/debug": "^4.1.5",
- "@types/faker": "^5.5.3",
- "@types/jest": "^26.0.22",
- "@types/node-fetch": "^2.5.10",
- "commitizen": "^4.2.4",
- "cz-conventional-changelog": "3.3.0",
- "faker": "^5.5.3",
- "jest": "^26.6.0",
- "msw": "latest",
- "node-fetch": "^2.6.1",
- "page-with": "^0.4.1",
- "prettier": "^2.2.1",
- "rimraf": "^3.0.2",
- "simple-git-hooks": "^2.7.0",
- "ts-jest": "^26.5.5",
- "ts-node": "^9.1.1",
- "typescript": "4.3.5"
+ "@ossjs/release": "^0.10.1",
+ "@playwright/test": "^1.59.1",
+ "@types/node": "^24.6.2",
+ "prettier": "^3.8.3",
+ "publint": "^0.3.18",
+ "tsdown": "^0.21.9",
+ "typescript": "^5.9.3",
+ "vite": "^8.0.8",
+ "vitest": "^4.1.4",
+ "zod": "^4.3.6"
},
"dependencies": {
- "@types/lodash": "^4.14.172",
- "@types/md5": "^2.3.0",
- "@types/pluralize": "^0.0.29",
- "@types/uuid": "^8.3.0",
- "date-fns": "^2.21.1",
- "debug": "^4.3.1",
- "graphql": "^15.5.0",
- "lodash": "^4.17.21",
- "md5": "^2.3.0",
- "outvariant": "^1.2.1",
- "pluralize": "^8.0.0",
- "strict-event-emitter": "^0.2.0",
- "uuid": "^8.3.1"
- },
- "optionalDependencies": {
- "msw": "latest"
- },
- "config": {
- "commitizen": {
- "path": "./node_modules/cz-conventional-changelog"
- }
+ "@standard-schema/spec": "^1.1.0",
+ "es-toolkit": "^1.45.1",
+ "mutative": "^1.3.0",
+ "outvariant": "^1.4.3",
+ "rettime": "^0.11.8"
}
-}
+}
\ No newline at end of file
diff --git a/playwright.config.ts b/playwright.config.ts
new file mode 100644
index 00000000..e588d7d7
--- /dev/null
+++ b/playwright.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+ testDir: './tests',
+ testMatch: '**/*.browser.test.ts',
+ workers: 1,
+ projects: [
+ {
+ use: devices['Desktop Chrome'],
+ },
+ ],
+})
diff --git a/playwright.extend.ts b/playwright.extend.ts
new file mode 100644
index 00000000..33c26af9
--- /dev/null
+++ b/playwright.extend.ts
@@ -0,0 +1,91 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { invariant } from 'outvariant'
+import { test as testBase, expect, type Page } from '@playwright/test'
+import { createServer, type ViteDevServer } from 'vite'
+
+interface Fixtures {
+ serve: >(
+ fn: () => Promise,
+ ) => Promise<{
+ url: URL
+ evaluate: any>(
+ callback: Callback,
+ options?: { page: Page },
+ ) => Promise>
+ }>
+}
+
+export { expect }
+
+export const test = testBase.extend({
+ async serve({ page }, use) {
+ let server: ViteDevServer | undefined
+
+ const directory = path.join(
+ process.cwd(),
+ './tests/.tmp',
+ test.info().testId,
+ )
+ const entryPath = path.join(directory, 'entry.ts')
+
+ await use(async (fn) => {
+ await fs.promises.mkdir(directory, { recursive: true })
+ await fs.promises.writeFile(
+ entryPath,
+ `window.__vite_playwright_context__ = await (${fn.toString()})();`,
+ 'utf8',
+ )
+
+ await fs.promises.writeFile(
+ path.join(directory, 'index.html'),
+ `
+
+ = {
+ /**
+ * A [Standard Schema](https://standardschema.dev/) describing the records in this collection.
+ */
+ schema: Schema
+ /**
+ * Extensions to apply to this collection.
+ */
+ extensions?: Array
+}
+
+export interface PaginationOptions {
+ /**
+ * A reference to a record to use as a cursor to start the querying from.
+ */
+ cursor?: RecordType>
+ /**
+ * A number of matching records to take (after `skip`, if any).
+ */
+ take?: number
+ /**
+ * A number of matching records to skip.
+ */
+ skip?: number
+}
+
+export interface UpdateOptions {
+ data: UpdateFunction
+}
+
+interface StrictOptions {
+ /**
+ * Throws an error if no records match the given query.
+ */
+ strict?: Strict
+}
+
+export type UpdateFunction = (draft: Draft) => Promise | void
+
+export type RecordType> = V & {
+ [kPrimaryKey]: string
+ [kRelationMap]: Map
+}
+
+export const kCollectionId = Symbol('kCollectionId')
+export const kPrimaryKey = Symbol('kPrimaryKey')
+export const kRelationMap = Symbol('kRelationMap')
+
+/**
+ * A collection of data.
+ * @example
+ * const users = new Collection({ schema: userSchema })
+ */
+export class Collection {
+ #records: Array>>
+ #logger: Logger
+
+ private [kCollectionId]: number
+
+ public hooks: Emitter>
+
+ constructor(private readonly options: CollectionOptions) {
+ this[kCollectionId] = this.#generateCollectionId()
+
+ this.#logger = new Logger('Collection').extend(this[kCollectionId])
+ this.#records = []
+
+ this.hooks = createHooksEmitter()
+ this.options.extensions?.forEach((extension) => extension.extend(this))
+ }
+
+ /**
+ * Creates a new record with the given values.
+ * @param initialValues Initial values for the new record.
+ * @return The created record.
+ *
+ * @example
+ * await users.create({ id: 1, name: 'John' })
+ */
+ public async create(
+ initialValues: StandardSchemaV1.InferInput,
+ ): Promise>> {
+ let logger = this.#logger.extend('create')
+ logger.log('initial values:', initialValues)
+
+ const { sanitizedInitialValues, restoreProperties } =
+ this.#sanitizeInitialValues(initialValues)
+
+ const validationResult = await this.options.schema['~standard'].validate(
+ sanitizedInitialValues,
+ )
+
+ if (validationResult.issues) {
+ console.error(validationResult.issues)
+
+ throw new OperationError(
+ 'Failed to create a new record with initial values: does not match the schema. Please see the schema validation errors above.',
+ OperationErrorCodes.INVALID_INITIAL_VALUES,
+ )
+ }
+
+ let record = validationResult.value as RecordType
+
+ invariant.as(
+ OperationError.for(OperationErrorCodes.INVALID_INITIAL_VALUES),
+ typeof record === 'object',
+ 'Failed to create a record with initial values (%j): expected the record to be an object or an array',
+ initialValues,
+ )
+
+ restoreProperties(record)
+
+ // Generate random primary key for every record.
+ const primaryKey =
+ (isObject(initialValues) &&
+ initialValues[kPrimaryKey as keyof typeof initialValues]) ||
+ crypto.randomUUID()
+
+ Object.defineProperties(record, {
+ [kPrimaryKey]: {
+ enumerable: false,
+ configurable: false,
+ value: primaryKey,
+ },
+ [kRelationMap]: {
+ enumerable: false,
+ configurable: false,
+ value: new Map>(),
+ },
+ })
+
+ logger = logger.extend(primaryKey)
+ logger.log('symbols defined!', record[kRelationMap])
+
+ if (this.hooks.listenerCount('create') > 0) {
+ await this.hooks.emitAsPromise(
+ new TypedEvent('create', { data: { record, initialValues } }),
+ )
+ }
+ logger.log('create hooks done!')
+
+ this.#records.push(record)
+ logger.log('create done!', record)
+
+ return record
+ }
+
+ /**
+ * Creates multiple records using the given initial values factory.
+ * @param count Number of records to create.
+ * @param initialValuesFactory Factory function to generate initial values for each record.
+ * @return Array of created records.
+ *
+ * @example
+ * await users.createMany(5, (index) => ({ id: index + 1}))
+ */
+ public async createMany(
+ count: number,
+ initialValuesFactory: (
+ index: number,
+ ) => StandardSchemaV1.InferInput,
+ ): Promise>>> {
+ const pendingPromises: Array> = []
+
+ for (let i = 0; i < count; i++) {
+ pendingPromises.push(this.create(initialValuesFactory(i)))
+ }
+
+ return await Promise.all(pendingPromises).catch((error) => {
+ throw new OperationError(
+ 'Failed to execute "createMany" on collection: unexpected error',
+ OperationErrorCodes.UNEXPECTED_ERROR,
+ error,
+ )
+ })
+ }
+
+ /**
+ * Returns the first record matching the query.
+ * If no query is provided, returns the first record in the collection.
+ * @example
+ * users.findFirst((q) => q.where({ id: 123 }))
+ */
+ public findFirst(
+ predicate?:
+ | ((query: Query>>) => Query)
+ | Query>>,
+ options?: StrictOptions,
+ ): Strict extends true
+ ? RecordType>
+ : RecordType> | undefined {
+ if (predicate == null) {
+ const firstRecord = this.#records[0]
+
+ invariant.as(
+ OperationError.for(OperationErrorCodes.STRICT_QUERY_WITHOUT_RESULTS),
+ options?.strict ? firstRecord != null : true,
+ 'Failed to execute "findFirst" on collection without a query: the collection is empty',
+ )
+
+ return firstRecord!
+ }
+
+ const result = this.#query(
+ predicate instanceof Query ? predicate : predicate(new Query()),
+ ).next().value
+
+ invariant.as(
+ OperationError.for(OperationErrorCodes.STRICT_QUERY_WITHOUT_RESULTS),
+ options?.strict ? result != null : true,
+ 'Failed to execute "findFirst" on collection: no record found matching the query',
+ )
+
+ return result!
+ }
+
+ /**
+ * Returns all records matching the query.
+ * If no query is provided, returns all records in the collection.
+ * @example
+ * users.findMany((q) => q.where({ subscribed: false }))
+ */
+ public findMany(
+ predicate?:
+ | ((query: Query>>) => Query)
+ | Query>>,
+ options?: PaginationOptions & SortOptions & StrictOptions,
+ ): Array>> {
+ const query =
+ predicate == null
+ ? new Query(() => true)
+ : predicate instanceof Query
+ ? predicate
+ : predicate(new Query())
+
+ const results = Array.from(this.#query(query, options)).filter(
+ (result) => !!result,
+ )
+
+ invariant.as(
+ OperationError.for(OperationErrorCodes.STRICT_QUERY_WITHOUT_RESULTS),
+ options?.strict ? results.length > 0 : true,
+ 'Failed to execute "findMany" on collection: no records found matching the query',
+ )
+
+ if (options?.orderBy) {
+ sortResults(options, results)
+ }
+
+ return results
+ }
+
+ /**
+ * Updates the first record matching the query.
+ * Returns the updated record.
+ * @example
+ * await users.update(
+ * (q) => q.where({ name: 'John' }),
+ * {
+ * data(user) {
+ * user.name = 'Johnatan'
+ * }
+ * }
+ * )
+ */
+ public async update(
+ predicate:
+ | ((query: Query>>) => Query)
+ | Query>>
+ | RecordType>,
+ options: UpdateOptions> &
+ StrictOptions,
+ ): Promise<
+ Strict extends true
+ ? RecordType>
+ : RecordType> | undefined
+ > {
+ const prevRecord = this.findFirst(
+ isRecord(predicate)
+ ? new Query((record) => {
+ return record[kPrimaryKey] === predicate[kPrimaryKey]
+ })
+ : predicate,
+ )
+
+ if (prevRecord == null) {
+ invariant.as(
+ OperationError.for(OperationErrorCodes.STRICT_QUERY_WITHOUT_RESULTS),
+ !options.strict,
+ 'Failed to execute "update" on collection: no record found matching the query',
+ )
+
+ return undefined!
+ }
+
+ const nextRecord = await this.#produceRecord(prevRecord, options.data)
+ this.#replaceRecord(prevRecord, nextRecord)
+
+ return nextRecord
+ }
+
+ /**
+ * Updates all records matching the query.
+ * Resolves to the list of updated records.
+ * @example
+ * await users.updateMany(
+ * (q) => q.where({ subscribed: false }),
+ * {
+ * data(user) {
+ * user.subscribed = true
+ * }
+ * }
+ * )
+ */
+ public async updateMany(
+ predicate:
+ | ((query: Query>>) => Query)
+ | Query>>,
+ options: UpdateOptions> &
+ SortOptions &
+ StrictOptions,
+ ): Promise>>> {
+ const prevRecords = this.findMany(predicate)
+
+ if (prevRecords.length === 0) {
+ invariant.as(
+ OperationError.for(OperationErrorCodes.STRICT_QUERY_WITHOUT_RESULTS),
+ !options.strict,
+ 'Failed to execute "updateMany" on collection: no records found matching the query',
+ )
+
+ return []
+ }
+
+ const nextRecords = []
+
+ for (const prevRecord of prevRecords) {
+ const nextRecord = await this.#produceRecord(prevRecord, options.data)
+ this.#replaceRecord(prevRecord, nextRecord)
+ nextRecords.push(nextRecord)
+ }
+
+ if (options.orderBy) {
+ sortResults(options, nextRecords)
+ }
+
+ return nextRecords
+ }
+
+ /**
+ * Deletes the first record matching the query.
+ * @example
+ * users.delete((q) => q.where({ id: 123 }))
+ */
+ public delete(
+ predicate:
+ | ((query: Query>>) => Query)
+ | Query>>
+ | RecordType>,
+ options?: StrictOptions,
+ ): Strict extends true
+ ? RecordType>
+ : RecordType> | undefined {
+ if (isRecord(predicate)) {
+ this.#deleteRecord(predicate)
+ return predicate
+ }
+
+ const record = this.findFirst(predicate)
+
+ if (record == null) {
+ invariant.as(
+ OperationError.for(OperationErrorCodes.STRICT_QUERY_WITHOUT_RESULTS),
+ !options?.strict,
+ 'Failed to execute "delete" on collection: no record found matching the query',
+ )
+
+ return undefined!
+ }
+
+ this.#deleteRecord(record)
+ return record
+ }
+
+ /**
+ * Deletes all records matching the query.
+ * @example
+ * users.deleteMany((q) => q.where({ subscribed: false }))
+ */
+ public deleteMany(
+ predicate:
+ | ((query: Query>>) => Query)
+ | Query>>,
+ options?: SortOptions & StrictOptions,
+ ): Array>> {
+ /**
+ * @note Do NOT forward the sorting options to the querying phase
+ * so the results are returned in the order they are present in the store.
+ * That way, we can delete them right-to-left correctly.
+ */
+ const records = this.findMany(predicate)
+
+ for (let i = records.length - 1; i >= 0; i--) {
+ this.#deleteRecord(records[i]!)
+ }
+
+ if (records.length === 0) {
+ invariant.as(
+ OperationError.for(OperationErrorCodes.STRICT_QUERY_WITHOUT_RESULTS),
+ !options?.strict,
+ 'Failed to execute "deleteMany" on collection: no records found matching the query',
+ )
+
+ return []
+ }
+
+ if (options?.orderBy) {
+ sortResults(options, records)
+ }
+
+ return records
+ }
+
+ /**
+ * Returns the total number of records in this collection.
+ * @example
+ * const users = new Collection({ schema })
+ * await users.create({ id: 1, name: 'John' })
+ * users.count() // 1
+ */
+ public count(): number {
+ return this.#records.length
+ }
+
+ /**
+ * Returns a list of all records from this collection.
+ */
+ public all(): Array>> {
+ /**
+ * @note Preserve exact record references so they might be used
+ * when querying (must contain primary keys).
+ */
+ return this.#records
+ }
+
+ /**
+ * Deletes all the records in this collection.
+ */
+ public clear(): void {
+ for (const record of this.#records) {
+ this.#deleteRecord(record)
+ }
+
+ this.#records.length = 0
+ }
+
+ /**
+ * Defines relations for the records in this collection.
+ * @example
+ * users.defineRelations(({ many }) => ({
+ * posts: many(posts),
+ * }))
+ */
+ public defineRelations(
+ resolver: RelationsFunction>,
+ ) {
+ let logger = this.#logger.extend('defineRelations')
+ logger.log('defining relations...')
+
+ const relations = toDeepEntries<() => Relation>(
+ resolver(createRelationBuilder(this)) as any,
+ )
+ logger.log('relations declaration:', relations)
+
+ const initializeRelations = (
+ record: RecordType,
+ initialValues: StandardSchemaV1.InferInput = record,
+ ) => {
+ for (const [path, createRelation] of relations) {
+ logger.log(`initializing relation for "${path.join('.')}"...`)
+
+ const relation = createRelation()
+ relation.initialize(record, path as Array, initialValues)
+
+ logger.log('relation initialized!', relation)
+ }
+ }
+
+ // Initialize relations for the existing records that were created
+ // before these relations were defined.
+ for (const record of this.#records) {
+ initializeRelations(record)
+ }
+
+ // Initialize relations for all records created from now on.
+ this.hooks.earlyOn('create', (event) => {
+ initializeRelations(event.data.record, event.data.initialValues)
+ })
+ }
+
+ /**
+ * Sanitizes the given object so it can be accepted as the input to Standard Schema validation.
+ * This removes getters to prevent potentially infinite object references in self-referencing
+ * relations. This also drops the internal symbols but gives a function to restore them back.
+ */
+ #sanitizeInitialValues(initialValues: unknown) {
+ const propertiesToRestore: Array<{
+ path: Array
+ descriptor: PropertyDescriptor
+ }> = []
+
+ // Track visited records by primary key to detect cycles
+ // in self-referencing relations. Only strip relation values
+ // when revisiting a record (i.e. an actual cycle), not for
+ // all nested records indiscriminately.
+ const visited = new Set()
+
+ const sanitize = (
+ value: unknown,
+ path: Array = [],
+ ): unknown => {
+ if (Array.isArray(value)) {
+ return value.map((value, index) => sanitize(value, path.concat(index)))
+ }
+
+ if (isObject(value)) {
+ const record = isRecord(value) ? value : undefined
+ const isRevisit = record != null && visited.has(record[kPrimaryKey])
+
+ if (record && !isRevisit) {
+ visited.add(record[kPrimaryKey])
+ }
+
+ const relations = record ? record[kRelationMap] : undefined
+
+ return Object.fromEntries(
+ Reflect.ownKeys(value).map((key) => {
+ const childValue = value[key as keyof typeof value]
+ const childPath = path.concat(key)
+
+ if (typeof key === 'symbol') {
+ /**
+ * @note Preserve primary keys on sanitized initial values.
+ * Otherwise, internal symbols are stripped off and record references are lost.
+ * This is curcial when handling relations for records that were created
+ * before the relation was defined.
+ */
+ if (key === kPrimaryKey) {
+ propertiesToRestore.push({
+ path: childPath,
+ descriptor: Object.getOwnPropertyDescriptor(value, key)!,
+ })
+ }
+ return [key, childValue]
+ }
+
+ const relation = relations?.get(key)
+
+ // Only strip relation values when revisiting a record
+ // to break self-referencing cycles. Non-circular nested
+ // relations are left intact for proper schema validation.
+ if (isRevisit && relation && childValue != null) {
+ propertiesToRestore.push({
+ path: childPath,
+ descriptor: Object.getOwnPropertyDescriptor(value, key)!,
+ })
+ return [key, relation.getDefaultValue()]
+ }
+
+ return [key, sanitize(childValue, childPath)]
+ }),
+ )
+ }
+
+ return value
+ }
+
+ const sanitizedInitialValues = sanitize(initialValues)
+
+ return {
+ sanitizedInitialValues,
+ /**
+ * Restores record properties that were stripped off during the sanitization
+ * (e.g. relational properties, internal symbols of records given as initial value, etc).
+ */
+ restoreProperties(record: RecordType): void {
+ for (const { path, descriptor } of propertiesToRestore) {
+ definePropertyAtPath(record, path, descriptor)
+ }
+ },
+ }
+ }
+
+ *#query(
+ query: Query>>,
+ options: PaginationOptions = { take: Infinity },
+ ): Generator<
+ RecordType> | undefined,
+ undefined,
+ RecordType> | undefined
+ > {
+ const { take, cursor, skip } = options
+
+ invariant(
+ skip !== undefined ? Number.isInteger(skip) && skip >= 0 : true,
+ 'Failed to query the collection: expected the "skip" pagination option to be a number larger or equal to 0 but got %j',
+ skip,
+ )
+
+ let taken = 0
+ let skipped = 0
+
+ // if (cursor != null) {
+ // const cursorIndex = store.findIndex((record) => {
+ // return record[kPrimaryKey] === cursor[kPrimaryKey]
+ // })
+
+ // if (cursorIndex === -1) {
+ // return
+ // }
+
+ // store = store.slice(cursorIndex + 1)
+ // }
+
+ const shouldTake = Math.abs(take ?? Infinity)
+ const delta = take && take < 0 ? -1 : 1
+ let start = delta === 1 ? 0 : this.#records.length - 1
+ const end = delta === 1 ? this.#records.length : -1
+
+ if (cursor != null) {
+ const cursorIndex = this.#records.findIndex((record) => {
+ return record[kPrimaryKey] === cursor[kPrimaryKey]
+ })
+
+ if (cursorIndex === -1) {
+ return
+ }
+
+ start = cursorIndex
+ }
+
+ for (let i = start; i !== end; i += delta) {
+ const record = this.#records[i]
+
+ if (record != null && query.test(record)) {
+ if (skip != null) {
+ if (skipped < skip) {
+ skipped++
+ continue
+ }
+ }
+
+ yield record
+ taken++
+ }
+
+ if (taken >= shouldTake) {
+ break
+ }
+ }
+ }
+
+ /**
+ * Returns the index of the given record in this collection.
+ * Performs a primary key-based lookup instead of a reference lookup
+ * because certain references (like root-level arrays) might become stale
+ * after updates, but will retain their primary keys.
+ */
+ #indexOf(record: RecordType): number {
+ return this.#records.findIndex((existingRecord) => {
+ return existingRecord[kPrimaryKey] === record[kPrimaryKey]
+ })
+ }
+
+ /**
+ * Replaces the given record with the next version of it.
+ */
+ #replaceRecord(prevRecord: RecordType, nextRecord: RecordType): void {
+ const index = this.#indexOf(prevRecord)
+
+ invariant(
+ index !== -1,
+ 'Failed to replace record "%j" with "%j": previous record not found',
+ prevRecord,
+ nextRecord,
+ )
+
+ this.#records[index] = nextRecord
+ }
+
+ /**
+ * Deletes the given record from the collection.
+ */
+ #deleteRecord(record: RecordType): void {
+ const index = this.#indexOf(record)
+
+ if (index !== -1) {
+ const deleteEvent = new TypedEvent('delete', {
+ data: { deletedRecord: record },
+ })
+ this.hooks.emit(deleteEvent)
+
+ if (!deleteEvent.defaultPrevented) {
+ this.#records.splice(index, 1)
+ }
+ }
+ }
+
+ /**
+ * Produces the next version of the given record by applying the `data` changes to it.
+ * Re-applies the schema to the end record to ensure validity and apply user-defined transforms.
+ */
+ async #produceRecord(
+ prevRecord: RecordType>,
+ updateData: UpdateOptions>['data'],
+ ): Promise>> {
+ const logger = this.#logger.extend('produceRecord')
+ logger.log('updating the record with options:', prevRecord, updateData)
+
+ /**
+ * @note Clone the previous record, preserving the symbols (so it's considered a record)
+ * but stripping off relational keys (getters) to preserve the values of foreign records
+ * at the moment of update.
+ */
+ const frozenPrevRecord = cloneWithInternals(
+ prevRecord,
+ ({ key, descriptor }) => {
+ return typeof key === 'symbol' && descriptor.get == null
+ },
+ )
+
+ invariant(
+ isRecord(frozenPrevRecord),
+ 'Failed to update a record (%j): frozen previous record copy is not a record',
+ prevRecord,
+ )
+
+ /**
+ * @note Build a draft input where relational getters are replaced with
+ * plain data descriptors holding their resolved values. `mutative` cannot
+ * observe mutations through getters (https://github.com/unadlib/mutative/issues/157),
+ * so a `push` on `draft.posts` is lost unless `posts` is a plain property.
+ * Live foreign record references (with their internal symbols) are preserved.
+ */
+ const draftInput = this.#buildDraftInput(prevRecord)
+
+ const [maybeNextRecord, patches, inversePatches] = await createDraft(
+ draftInput,
+ updateData,
+ {
+ strict: false,
+ enablePatches: true,
+ },
+ )
+
+ Object.defineProperties(maybeNextRecord, {
+ [kPrimaryKey]: {
+ value: prevRecord[kPrimaryKey],
+ enumerable: false,
+ configurable: false,
+ },
+ [kRelationMap]: {
+ value: prevRecord[kRelationMap],
+ enumerable: false,
+ configurable: false,
+ },
+ })
+
+ invariant(
+ isRecord(maybeNextRecord),
+ 'Failed to update a record (%j): a record produced by the draft is not a record',
+ prevRecord,
+ )
+
+ // Route the updates produces by the draft through the hooks
+ // so the hooks could reverse some of them.
+ const patchesToUndo: Array = []
+
+ /**
+ * @note Collapse per-index patches under a relation path into a single
+ * relation-level event. `draft.posts.push(x)` emits `{path: ['posts', N]}`,
+ * but relation handlers expect `{path: ['posts'], nextValue: }`.
+ */
+ const relationPaths: Array> = []
+ for (const serializedPath of prevRecord[kRelationMap].keys()) {
+ relationPaths.push(serializedPath.split('.'))
+ }
+
+ type RelationPatchGroup = {
+ relationPath: Array
+ patchIndices: Array
+ }
+ const relationGroups = new Map()
+ const passthroughIndices: Array = []
+
+ for (let i = 0; i < patches.length; i++) {
+ const patch = patches[i]
+ if (!patch) {
+ continue
+ }
+
+ const matchingRelationPath = relationPaths.find((relationPath) => {
+ if (patch.path.length !== relationPath.length + 1) {
+ return false
+ }
+ if (!relationPath.every((key, index) => key === patch.path[index])) {
+ return false
+ }
+ const nextSegment = patch.path[relationPath.length]
+ return typeof nextSegment === 'number' || nextSegment === 'length'
+ })
+
+ if (matchingRelationPath) {
+ const groupKey = matchingRelationPath.join('.')
+ const group = relationGroups.get(groupKey) ?? {
+ relationPath: matchingRelationPath,
+ patchIndices: [],
+ }
+ group.patchIndices.push(i)
+ relationGroups.set(groupKey, group)
+ } else {
+ passthroughIndices.push(i)
+ }
+ }
+
+ for (const i of passthroughIndices) {
+ const patch = patches[i]!
+
+ const updateEvent = new TypedEvent('update', {
+ data: {
+ prevRecord: frozenPrevRecord,
+ nextRecord: maybeNextRecord,
+ path: patch.path,
+ prevValue: get(prevRecord, patch.path),
+ nextValue: patch.value,
+ },
+ })
+
+ this.hooks.emit(updateEvent)
+
+ if (updateEvent.defaultPrevented) {
+ const inversePatch = inversePatches[i]
+
+ invariant(
+ inversePatch != null,
+ 'Failed to update a record (%j): missing inverse patch at index %d',
+ prevRecord,
+ i,
+ )
+
+ patchesToUndo.push(inversePatch)
+ }
+ }
+
+ for (const group of relationGroups.values()) {
+ const updateEvent = new TypedEvent('update', {
+ data: {
+ prevRecord: frozenPrevRecord,
+ nextRecord: maybeNextRecord,
+ path: group.relationPath,
+ prevValue: get(prevRecord, group.relationPath),
+ nextValue: get(maybeNextRecord, group.relationPath),
+ },
+ })
+
+ this.hooks.emit(updateEvent)
+
+ if (updateEvent.defaultPrevented) {
+ for (const i of group.patchIndices) {
+ const inversePatch = inversePatches[i]
+
+ invariant(
+ inversePatch != null,
+ 'Failed to update a record (%j): missing inverse patch at index %d',
+ prevRecord,
+ i,
+ )
+
+ patchesToUndo.push(inversePatch)
+ }
+ }
+ }
+
+ const nextRecord =
+ patchesToUndo.length > 0
+ ? apply(maybeNextRecord, patchesToUndo)
+ : maybeNextRecord
+
+ logger.log('re-applying the schema...')
+ const { sanitizedInitialValues } = this.#sanitizeInitialValues(nextRecord)
+ const validationResult = await this.options.schema['~standard'].validate(
+ sanitizedInitialValues,
+ )
+
+ if (validationResult.issues) {
+ console.error(validationResult.issues)
+ throw new InvariantError(
+ 'Failed to update record (%j): resulting record does not match the schema',
+ frozenPrevRecord,
+ )
+ }
+
+ const finalRecord = validationResult.value as RecordType
+ logger.log('schema re-applied!')
+
+ const descriptors = Object.getOwnPropertyDescriptors(prevRecord)
+ for (const key of Reflect.ownKeys(descriptors)) {
+ const descriptor = descriptors[key as keyof typeof descriptors]
+ if (typeof key === 'symbol' || typeof descriptor.get === 'function') {
+ Object.defineProperty(finalRecord, key, descriptor)
+ }
+ }
+
+ return finalRecord
+ }
+
+ /**
+ * Build a draftable copy of the record where relational getters are replaced
+ * with data descriptors holding their resolved values. `mutative` cannot
+ * observe mutations through getters (https://github.com/unadlib/mutative/issues/157),
+ * so a `push` on `draft.posts` is lost unless `posts` is a plain property.
+ * Live foreign record references (with their internal symbols) are preserved
+ * so downstream hooks can resolve primary keys on the drafted elements.
+ */
+ #buildDraftInput(record: T): T {
+ const clone = cloneWithInternals(
+ record,
+ ({ key, descriptor }) =>
+ typeof key === 'symbol' && descriptor.get == null,
+ )
+
+ for (const serializedPath of record[kRelationMap].keys()) {
+ const path = serializedPath.split('.')
+ definePropertyAtPath(clone, path, {
+ value: get(record, path),
+ writable: true,
+ enumerable: true,
+ configurable: true,
+ })
+ }
+
+ return clone
+ }
+
+ /**
+ * Returns a reproducible collection ID number based on the collection
+ * creation order. Collection ID has to be reproducible across runtimes
+ * to enable synchronization.
+ */
+ #generateCollectionId(): number {
+ collectionsCreated++
+ const seed = 0
+ const value = collectionsCreated.toString()
+
+ let h1 = 0xdeadbeef ^ seed,
+ h2 = 0x41c6ce57 ^ seed
+ for (let i = 0, ch; i < value.length; i++) {
+ ch = value.charCodeAt(i)
+ h1 = Math.imul(h1 ^ ch, 2654435761)
+ h2 = Math.imul(h2 ^ ch, 1597334677)
+ }
+ h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507)
+ h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909)
+ h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507)
+ h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909)
+
+ return 4294967296 * (2097151 & h2) + (h1 >>> 0)
+ }
+}
diff --git a/src/comparators/boolean.ts b/src/comparators/boolean.ts
deleted file mode 100644
index e1afb636..00000000
--- a/src/comparators/boolean.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { BooleanQuery, QueryToComparator } from '../query/queryTypes'
-
-export const booleanComparators: QueryToComparator = {
- equals(expected, actual) {
- return actual === expected
- },
- notEquals(expected, actual) {
- return expected !== actual
- },
-}
diff --git a/src/comparators/date.ts b/src/comparators/date.ts
deleted file mode 100644
index bdebe2ae..00000000
--- a/src/comparators/date.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import { compareAsc as compareDates } from 'date-fns'
-import { DateQuery, QueryToComparator } from '../query/queryTypes'
-
-export const dateComparators: QueryToComparator = {
- equals(expected, actual) {
- return compareDates(expected, actual) === 0
- },
- notEquals(expected, actual) {
- return compareDates(expected, actual) !== 0
- },
- gt(expected, actual) {
- return compareDates(actual, expected) === 1
- },
- gte(expected, actual) {
- return [0, 1].includes(compareDates(actual, expected))
- },
- lt(expected, actual) {
- return compareDates(actual, expected) === -1
- },
- lte(expected, actual) {
- return [-1, 0].includes(compareDates(actual, expected))
- },
-}
diff --git a/src/comparators/number.ts b/src/comparators/number.ts
deleted file mode 100644
index f56a0594..00000000
--- a/src/comparators/number.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { NumberQuery, QueryToComparator } from '../query/queryTypes'
-import { numberInRange } from '../utils/numberInRange'
-
-export const numberComparators: QueryToComparator = {
- equals(expected, actual) {
- return actual === expected
- },
- notEquals(expected, actual) {
- return !numberComparators.equals(expected, actual)
- },
- between(expected, actual) {
- return numberInRange(expected[0], expected[1], actual)
- },
- notBetween(expected, actual) {
- return !numberComparators.between(expected, actual)
- },
- gt(expected, actual) {
- return actual > expected
- },
- gte(expected, actual) {
- return actual >= expected
- },
- lt(expected, actual) {
- return actual < expected
- },
- lte(expected, actual) {
- return actual <= expected
- },
- in(expected, actual) {
- return expected.includes(actual)
- },
- notIn(expected, actual) {
- return !numberComparators.in(expected, actual)
- },
-}
diff --git a/src/comparators/string.ts b/src/comparators/string.ts
deleted file mode 100644
index a44d2ac5..00000000
--- a/src/comparators/string.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import { QueryToComparator, StringQuery } from '../query/queryTypes'
-
-export const stringComparators: QueryToComparator = {
- equals(expected, actual) {
- return expected === actual
- },
- notEquals(expected, actual) {
- return !stringComparators.equals(expected, actual)
- },
- contains(expected, actual) {
- return actual.includes(expected)
- },
- notContains(expected, actual) {
- return !stringComparators.contains(expected, actual)
- },
- in(expected, actual) {
- return expected.includes(actual)
- },
- notIn(expected, actual) {
- return !stringComparators.in(expected, actual)
- },
-}
diff --git a/src/db/Database.ts b/src/db/Database.ts
deleted file mode 100644
index 92745e13..00000000
--- a/src/db/Database.ts
+++ /dev/null
@@ -1,177 +0,0 @@
-import md5 from 'md5'
-import { invariant } from 'outvariant'
-import { StrictEventEmitter } from 'strict-event-emitter'
-import {
- Entity,
- ENTITY_TYPE,
- KeyType,
- ModelDictionary,
- PrimaryKeyType,
- PRIMARY_KEY,
-} from '../glossary'
-
-export const SERIALIZED_INTERNAL_PROPERTIES_KEY =
- 'SERIALIZED_INTERNAL_PROPERTIES'
-
-type Models = Record<
- keyof Dictionary,
- Map>
->
-
-export interface SerializedInternalEntityProperties {
- entityType: string
- primaryKey: PrimaryKeyType
-}
-
-export interface SerializedEntity extends Entity {
- [SERIALIZED_INTERNAL_PROPERTIES_KEY]: SerializedInternalEntityProperties
-}
-
-export type DatabaseMethodToEventFn = (
- sourceId: string,
- args: ArgsType,
-) => void
-
-export interface DatabaseEventsMap {
- create: DatabaseMethodToEventFn<
- [
- modelName: KeyType,
- entity: SerializedEntity,
- customPrimaryKey?: PrimaryKeyType,
- ]
- >
- update: DatabaseMethodToEventFn<
- [
- modelName: KeyType,
- prevEntity: SerializedEntity,
- nextEntity: SerializedEntity,
- ]
- >
- delete: DatabaseMethodToEventFn<
- [modelName: KeyType, primaryKey: PrimaryKeyType]
- >
-}
-
-let callOrder = 0
-
-export class Database {
- public id: string
- public events: StrictEventEmitter
- private models: Models
-
- constructor(dictionary: Dictionary) {
- this.events = new StrictEventEmitter()
- this.models = Object.keys(dictionary).reduce>(
- (acc, modelName: keyof Dictionary) => {
- acc[modelName] = new Map>()
- return acc
- },
- {} as Models,
- )
-
- callOrder++
- this.id = this.generateId()
- }
-
- /**
- * Generates a unique MD5 hash based on the database
- * module location and invocation order. Used to reproducibly
- * identify a database instance among sibling instances.
- */
- private generateId() {
- const { stack } = new Error()
- const callFrame = stack?.split('\n')[4]
- const salt = `${callOrder}-${callFrame?.trim()}`
- return md5(salt)
- }
-
- private serializeEntity(entity: Entity): SerializedEntity {
- return {
- ...entity,
- [SERIALIZED_INTERNAL_PROPERTIES_KEY]: {
- entityType: entity[ENTITY_TYPE],
- primaryKey: entity[PRIMARY_KEY],
- },
- }
- }
-
- getModel(name: ModelName) {
- return this.models[name]
- }
-
- create(
- modelName: ModelName,
- entity: Entity,
- customPrimaryKey?: PrimaryKeyType,
- ): Map> {
- invariant(
- entity[ENTITY_TYPE],
- 'Failed to create a new "%s" record: provided entity has no type. %j',
- modelName,
- entity,
- )
- invariant(
- entity[PRIMARY_KEY],
- 'Failed to create a new "%s" record: provided entity has no primary key. %j',
- modelName,
- entity,
- )
-
- const primaryKey =
- customPrimaryKey || (entity[entity[PRIMARY_KEY]] as string)
-
- this.events.emit('create', this.id, [
- modelName,
- this.serializeEntity(entity),
- customPrimaryKey,
- ])
- return this.getModel(modelName).set(primaryKey, entity)
- }
-
- update(
- modelName: ModelName,
- prevEntity: Entity,
- nextEntity: Entity,
- ): void {
- const prevPrimaryKey = prevEntity[prevEntity[PRIMARY_KEY]] as PrimaryKeyType
- const nextPrimaryKey = nextEntity[prevEntity[PRIMARY_KEY]] as PrimaryKeyType
-
- if (nextPrimaryKey !== prevPrimaryKey) {
- this.delete(modelName, prevPrimaryKey)
- }
-
- this.getModel(modelName).set(nextPrimaryKey, nextEntity)
-
- // this.create(modelName, nextEntity, nextPrimaryKey)
- this.events.emit('update', this.id, [
- modelName,
- this.serializeEntity(prevEntity),
- this.serializeEntity(nextEntity),
- ])
- }
-
- delete(
- modelName: ModelName,
- primaryKey: PrimaryKeyType,
- ): void {
- this.getModel(modelName).delete(primaryKey)
- this.events.emit('delete', this.id, [modelName, primaryKey])
- }
-
- has(
- modelName: ModelName,
- primaryKey: PrimaryKeyType,
- ): boolean {
- return this.getModel(modelName).has(primaryKey)
- }
-
- count(modelName: ModelName) {
- return this.getModel(modelName).size
- }
-
- listEntities(
- modelName: ModelName,
- ): Entity[] {
- return Array.from(this.getModel(modelName).values())
- }
-}
diff --git a/src/db/drop.ts b/src/db/drop.ts
deleted file mode 100644
index 8f382b30..00000000
--- a/src/db/drop.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { FactoryAPI } from '../glossary'
-
-export function drop(factoryApi: FactoryAPI): void {
- Object.values(factoryApi).forEach((model) => {
- model.deleteMany({ where: {} })
- })
-}
diff --git a/src/errors.ts b/src/errors.ts
new file mode 100644
index 00000000..bce08cc4
--- /dev/null
+++ b/src/errors.ts
@@ -0,0 +1,56 @@
+import type { Collection } from '#/src/collection.js'
+import type { PropertyPath } from '#/src/utils.js'
+import type { RelationDeclarationOptions } from '#/src/relation.js'
+
+export enum OperationErrorCodes {
+ UNEXPECTED_ERROR = 'UNEXPECTED_ERROR',
+ INVALID_INITIAL_VALUES = 'INVALID_INITIAL_VALUES',
+ STRICT_QUERY_WITHOUT_RESULTS = 'STRICT_QUERY_WITHOUT_RESULTS',
+}
+
+export class OperationError extends Error {
+ static for(code: OperationErrorCodes) {
+ return (message: string) => {
+ return new OperationError(message, code)
+ }
+ }
+
+ constructor(
+ message: string,
+ public readonly code: OperationErrorCodes,
+ public readonly cause?: unknown,
+ ) {
+ super(message)
+ }
+}
+
+export enum RelationErrorCodes {
+ RELATION_NOT_READY = 'RELATION_NOT_READY',
+ UNEXPECTED_SET_EXPRESSION = 'UNEXPECTED_SET_EXPRESSION',
+ INVALID_FOREIGN_RECORD = 'INVALID_FOREIGN_RECORD',
+ FORBIDDEN_UNIQUE_CREATE = 'FORBIDDEN_UNIQUE_CREATE',
+ FORBIDDEN_UNIQUE_UPDATE = 'FORBIDDEN_UNIQUE_UPDATE',
+}
+
+export interface RelationErrorDetails {
+ path: PropertyPath
+ ownerCollection: Collection
+ foreignCollections: Array>
+ options: RelationDeclarationOptions
+}
+
+export class RelationError extends Error {
+ static for(code: RelationErrorCodes, details: RelationErrorDetails) {
+ return (message: string) => {
+ return new RelationError(message, code, details)
+ }
+ }
+
+ constructor(
+ message: string,
+ public readonly code: RelationErrorCodes,
+ public readonly details: RelationErrorDetails,
+ ) {
+ super(message)
+ }
+}
diff --git a/src/errors/OperationError.ts b/src/errors/OperationError.ts
deleted file mode 100644
index 961379a0..00000000
--- a/src/errors/OperationError.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-export enum OperationErrorType {
- MissingPrimaryKey = 'MissingPrimaryKey',
- DuplicatePrimaryKey = 'DuplicatePrimaryKey',
- EntityNotFound = 'EntityNotFound',
-}
-
-export class OperationError extends Error {
- public type: ErrorType
-
- constructor(type: ErrorType, message?: string) {
- super(message)
- this.name = 'OperationError'
- this.type = type
- }
-}
diff --git a/src/extensions/index.ts b/src/extensions/index.ts
new file mode 100644
index 00000000..13dd2278
--- /dev/null
+++ b/src/extensions/index.ts
@@ -0,0 +1,21 @@
+import type { Collection } from '#/src/collection.js'
+
+export interface Extension {
+ /**
+ * Name of your extension.
+ */
+ name: string
+
+ /**
+ * A function that is called when your extension is applied by a collection.
+ * @param collection Reference to the `Collection` instance that applies the extension.
+ */
+ extend: (collection: Collection) => void
+}
+
+/**
+ * Creates a new extension.
+ */
+export function defineExtension(options: Extension): Extension {
+ return options
+}
diff --git a/src/extensions/persist.ts b/src/extensions/persist.ts
new file mode 100644
index 00000000..3380c312
--- /dev/null
+++ b/src/extensions/persist.ts
@@ -0,0 +1,182 @@
+import { invariant } from 'outvariant'
+import { unset } from 'es-toolkit/compat'
+import { defineExtension } from '#/src/extensions/index.js'
+import {
+ kCollectionId,
+ kPrimaryKey,
+ kRelationMap,
+ type Collection,
+ type RecordType,
+} from '#/src/collection.js'
+import { Logger } from '#/src/logger.js'
+import type { PropertyPath } from '#/src/utils.js'
+
+const STORAGE_KEY = 'msw/data/storage'
+const METADATA_KEY = '__metadata__'
+
+interface SerializedCollection {
+ version: number
+ collectionId: number
+ records: Array
+}
+
+export interface SerializedRecord {
+ [key: string]: unknown
+ [METADATA_KEY]: RecordMetadata
+}
+
+interface RecordMetadata {
+ primaryKey: string
+ relations: Array<{
+ path: PropertyPath
+ foreignKeys: Array
+ }>
+}
+
+/**
+ * Persists the collection between page reloads.
+ */
+export function persist() {
+ return defineExtension({
+ name: 'persist',
+ async extend(collection) {
+ if (
+ typeof window === 'undefined' ||
+ typeof localStorage === 'undefined'
+ ) {
+ return
+ }
+
+ const logger = new Logger('extension').extend('persist')
+ const COLLECTION_KEY = `${STORAGE_KEY}/${collection[kCollectionId]}`
+
+ // Flush the collection's on page unload.
+ window.addEventListener('unload', () => {
+ localStorage.setItem(
+ COLLECTION_KEY,
+ /**
+ * @fixme Stringifying relations errors because they produce
+ * circular structures. Relations have to be stripped out of the records.
+ * Maybe preserved in the metadata?
+ */
+ JSON.stringify({
+ version: 1,
+ collectionId: collection[kCollectionId],
+ records: collection.all().map(serializeRecord),
+ } satisfies SerializedCollection),
+ )
+ })
+
+ const rawPersistedData = localStorage.getItem(COLLECTION_KEY)
+
+ if (!rawPersistedData) {
+ return
+ }
+ const persistedData = JSON.parse(rawPersistedData) as SerializedCollection
+
+ invariant(
+ persistedData.collectionId === collection[kCollectionId],
+ 'Failed to hydrate data for collection "%s": parsed a state of an unknown collection "%s"',
+ collection[kCollectionId],
+ persistedData.collectionId,
+ )
+
+ logger.log(`found (${persistedData.records.length}) records to hydrate!`)
+
+ await Promise.all(
+ persistedData.records.map(async (serializedRecord) => {
+ logger.log('hydrating record...', { serializedRecord })
+ await createFromSerializedRecord(collection, serializedRecord)
+ }),
+ )
+
+ logger.log('hydration done!', collection.all())
+ },
+ })
+}
+
+export function serializeRecord(record: RecordType): SerializedRecord {
+ const result = structuredClone(record) as any as SerializedRecord
+
+ const metadata: RecordMetadata = {
+ primaryKey: record[kPrimaryKey],
+ relations: [],
+ }
+
+ // Delete relational keys since they can produce non-serializable structures.
+ const relations = record[kRelationMap]
+ for (const [path, relation] of relations) {
+ metadata.relations.push({
+ path: relation.path,
+ foreignKeys: Array.from(relation.foreignKeys),
+ })
+
+ unset(result, path)
+ }
+
+ result[METADATA_KEY] = metadata
+
+ return result
+}
+
+export function deserializeRecord(
+ record: SerializedRecord,
+): Record {
+ const metadata = record[METADATA_KEY]
+
+ invariant(
+ metadata,
+ 'Failed to deserialize record (%j): metadata is missing',
+ record,
+ )
+
+ // Restore the primary key for this record so it's preserved across reloads.
+ Object.defineProperties(record, {
+ [kPrimaryKey]: {
+ enumerable: false,
+ configurable: false,
+ value: metadata.primaryKey,
+ },
+ })
+
+ delete record[METADATA_KEY as keyof typeof record]
+
+ invariant(
+ !(METADATA_KEY in record),
+ 'Failed to deserialize record (%j): metadata not cleared',
+ record,
+ )
+
+ return record
+}
+
+export async function createFromSerializedRecord(
+ collection: Collection,
+ serializedRecord: SerializedRecord,
+): Promise {
+ const metadata = serializedRecord[METADATA_KEY]
+ const initialValues = deserializeRecord(serializedRecord)
+
+ invariant(
+ !(METADATA_KEY in initialValues),
+ 'Failed to create record from deserialized record (%j): metadata not cleared',
+ initialValues,
+ )
+
+ const record: RecordType = await collection.create(initialValues)
+ const relationMap = record[kRelationMap]
+
+ for (const serializedRelation of metadata.relations) {
+ const relation = relationMap.get(serializedRelation.path.join('.'))
+
+ if (relation == null) {
+ continue
+ }
+
+ for (const foreignKey of serializedRelation.foreignKeys) {
+ relation.foreignKeys.add(foreignKey)
+ }
+ }
+
+ return record
+}
diff --git a/src/extensions/sync.ts b/src/extensions/sync.ts
index 90bb4576..44a0420e 100644
--- a/src/extensions/sync.ts
+++ b/src/extensions/sync.ts
@@ -1,134 +1,232 @@
-import { ENTITY_TYPE, PRIMARY_KEY, Entity } from '../glossary'
+import { set } from 'es-toolkit/compat'
+import { defineExtension } from '#/src/extensions/index.js'
import {
- Database,
- DatabaseEventsMap,
- SerializedEntity,
- SERIALIZED_INTERNAL_PROPERTIES_KEY,
-} from '../db/Database'
-import { inheritInternalProperties } from '../utils/inheritInternalProperties'
-
-export type DatabaseMessageEventData =
+ kCollectionId,
+ kPrimaryKey,
+ kRelationMap,
+ type Collection,
+ type RecordType,
+} from '#/src/collection.js'
+import type { Query } from '#/src/query.js'
+import { isObject, type PropertyPath } from '#/src/utils.js'
+import { Logger } from '#/src/logger.js'
+import {
+ serializeRecord,
+ createFromSerializedRecord,
+ type SerializedRecord,
+} from '#/src/extensions/persist.js'
+
+type BroadcastOperation =
| {
- operationType: 'create'
- payload: Parameters
+ type: 'create'
+ senderId: Collection[typeof kCollectionId]
+ record: SerializedRecord
}
| {
- operationType: 'update'
- payload: Parameters
+ type: 'update'
+ senderId: Collection[typeof kCollectionId]
+ primaryKey: string
+ path: PropertyPath
+ nextValue: unknown
}
| {
- operationType: 'delete'
- payload: Parameters
+ type: 'delete'
+ senderId: Collection[typeof kCollectionId]
+ primaryKey: string
}
-function removeListeners(
- event: Event,
- db: Database,
-) {
- const listeners = db.events.listeners(event) as DatabaseEventsMap[Event][]
-
- listeners.forEach((listener) => {
- db.events.removeListener(event, listener)
- })
-
- return () => {
- listeners.forEach((listener) => {
- db.events.addListener(event, listener)
- })
- }
-}
+const BROADCAST_CHANNEL_NAME = 'msw/data/sync'
/**
- * Sets the serialized internal properties as symbols
- * on the given entity.
- * @note `Symbol` properties are stripped off when sending
- * an object over an event emitter.
+ * Synchronizes collection operations (create/update/delete)
+ * with the same collection in another browser tab(s).
*/
-function deserializeEntity(entity: SerializedEntity): Entity {
- const {
- [SERIALIZED_INTERNAL_PROPERTIES_KEY]: internalProperties,
- ...publicProperties
- } = entity
-
- inheritInternalProperties(publicProperties, {
- [ENTITY_TYPE]: internalProperties.entityType,
- [PRIMARY_KEY]: internalProperties.primaryKey,
- })
-
- return publicProperties
-}
-
-/**
- * Synchronizes database operations across multiple clients.
- */
-export function sync(db: Database) {
- const IS_BROWSER = typeof window !== 'undefined'
- const SUPPORTS_BROADCAST_CHANNEL = typeof BroadcastChannel !== 'undefined'
-
- if (!IS_BROWSER || !SUPPORTS_BROADCAST_CHANNEL) {
- return
- }
+export function sync() {
+ const logger = new Logger('extension').extend('sync')
+
+ return defineExtension({
+ name: 'sync',
+ extend(collection) {
+ if (
+ typeof window === 'undefined' ||
+ typeof BroadcastChannel === 'undefined'
+ ) {
+ return
+ }
- const channel = new BroadcastChannel('mswjs/data/sync')
+ const channel = new BroadcastChannel(BROADCAST_CHANNEL_NAME)
+ const hookContext = { skip: false }
- channel.addEventListener(
- 'message',
- (event: MessageEvent) => {
- const [sourceId] = event.data.payload
+ logger.log('applying extension...', { channel })
- // Ignore messages originating from unrelated databases.
- // Useful in case of multiple databases on the same page.
- if (db.id !== sourceId) {
- return
+ const performWithoutBroadcasting = async (
+ callback: () => Promise,
+ ): Promise => {
+ try {
+ hookContext.skip = true
+ await callback()
+ } finally {
+ hookContext.skip = false
+ }
}
- // Remove database event listener for the signaled operation
- // to prevent an infinite loop when applying this operation.
- const restoreListeners = removeListeners(event.data.operationType, db)
-
- // Apply the database operation signaled from another client
- // to the current database instance.
- switch (event.data.operationType) {
- case 'create': {
- const [modelName, entity, customPrimaryKey] = event.data.payload[1]
- db.create(modelName, deserializeEntity(entity), customPrimaryKey)
- break
+ channel.onmessage = async (event: MessageEvent) => {
+ const { data } = event
+
+ if (!isObject(data)) {
+ return
}
- case 'update': {
- const [modelName, prevEntity, nextEntity] = event.data.payload[1]
- db.update(
- modelName,
- deserializeEntity(prevEntity),
- deserializeEntity(nextEntity),
+ logger.log(
+ `sync event from another collection (${event.data.type})`,
+ event,
+ )
+
+ // Ignore sync events from irrelevant collections.
+ // This only works because collection ID is based on the call order
+ // and remains reproducible across runtimes.
+ if (data.senderId !== collection[kCollectionId]) {
+ logger.log(
+ `sender id (${data.senderId}) differs from this collection id (${collection[kCollectionId]}), skipping...`,
)
- break
+ return
}
- default: {
- db[event.data.operationType](...event.data.payload[1])
+ switch (data.type) {
+ case 'create': {
+ logger.warn('creating new record...', data)
+
+ /**
+ * @note Use the `.create()` method to correctly evolve the schema.
+ * This way, non-serializable schemas can survive sync as long as
+ * the initial values are serializable.
+ */
+ await performWithoutBroadcasting(async () => {
+ const record = await createFromSerializedRecord(
+ collection,
+ data.record,
+ )
+
+ /**
+ * @note Extraneous records might not have been associated with their owners
+ * at the time of sync. Manually ensure the owner is referenced in those relations.
+ */
+ record[kRelationMap].forEach((relation) => {
+ relation.foreignCollections.forEach((foreignCollection) => {
+ const foreignRecords = foreignCollection.findMany((q) =>
+ q.where((foreignRecord) => {
+ return relation.foreignKeys.has(
+ foreignRecord[kPrimaryKey],
+ )
+ }),
+ )
+
+ const foreignRelations = foreignRecords.flatMap(
+ (foreignRecord) => {
+ return relation.getRelationsToOwner(foreignRecord)
+ },
+ )
+ foreignRelations.forEach((foreignRelation) => {
+ foreignRelation.foreignKeys.add(record[kPrimaryKey])
+ })
+ })
+ })
+ })
+ break
+ }
+
+ case 'update': {
+ logger.log('updating record...')
+
+ await performWithoutBroadcasting(async () => {
+ await collection.update(
+ (q: Query) =>
+ q.where((record: RecordType) => {
+ return record[kPrimaryKey] === data.primaryKey
+ }),
+ {
+ data(record) {
+ set(record, data.path, data.nextValue)
+ },
+ },
+ )
+ })
+ break
+ }
+
+ case 'delete': {
+ logger.log('deleting record...')
+
+ await performWithoutBroadcasting(async () => {
+ collection.delete((q: Query) =>
+ q.where((record: RecordType) => {
+ return record[kPrimaryKey] === data.primaryKey
+ }),
+ )
+ })
+ break
+ }
+
+ default: {
+ // @ts-expect-error Runtime validation.
+ throw new Error(`Unknown sync event type "${data.type}"`)
+ }
}
}
- // Re-attach database event listeners.
- restoreListeners()
- },
- )
-
- // Broadcast the emitted event from this client
- // to all the other connected clients.
- function broadcastDatabaseEvent(
- operationType: Event,
- ) {
- return (...payload: Parameters) => {
- channel.postMessage({
- operationType,
- payload,
- } as DatabaseMessageEventData)
- }
- }
+ channel.onmessageerror = (event) => {
+ logger.log('sync channel error!', event)
+ }
+
+ const broadcastOperation = (operation: BroadcastOperation): void => {
+ logger.log('broadcasting...', operation)
+ channel.postMessage(operation)
+ }
- db.events.on('create', broadcastDatabaseEvent('create'))
- db.events.on('update', broadcastDatabaseEvent('update'))
- db.events.on('delete', broadcastDatabaseEvent('delete'))
+ collection.hooks.on('create', (event) => {
+ const { record, initialValues } = event.data
+
+ logger.warn(
+ 'record created, should broadcast?',
+ { record, initialValues },
+ !hookContext.skip,
+ )
+
+ if (!hookContext.skip) {
+ broadcastOperation({
+ type: 'create',
+ senderId: collection[kCollectionId],
+ record: serializeRecord(record),
+ })
+ }
+ })
+
+ collection.hooks.on('update', (event) => {
+ const { prevRecord, path, nextValue } = event.data
+ logger.log('record updated, should broadcast?', !hookContext.skip)
+
+ if (!hookContext.skip) {
+ broadcastOperation({
+ type: 'update',
+ senderId: collection[kCollectionId],
+ primaryKey: prevRecord[kPrimaryKey],
+ path,
+ nextValue,
+ })
+ }
+ })
+
+ collection.hooks.on('delete', (event) => {
+ logger.log('record deleted, should broadcast?', !hookContext.skip)
+
+ if (!hookContext.skip) {
+ broadcastOperation({
+ type: 'delete',
+ senderId: collection[kCollectionId],
+ primaryKey: event.data.deletedRecord[kPrimaryKey],
+ })
+ }
+ })
+ },
+ })
}
diff --git a/src/factory.ts b/src/factory.ts
deleted file mode 100644
index 96c368ae..00000000
--- a/src/factory.ts
+++ /dev/null
@@ -1,295 +0,0 @@
-import { format } from 'outvariant'
-import {
- DATABASE_INSTANCE,
- Entity,
- FactoryAPI,
- ModelAPI,
- ModelDefinition,
- ModelDictionary,
- PRIMARY_KEY,
-} from './glossary'
-import { first } from './utils/first'
-import { executeQuery } from './query/executeQuery'
-import { parseModelDefinition } from './model/parseModelDefinition'
-import { createModel } from './model/createModel'
-import { updateEntity } from './model/updateEntity'
-import { OperationError, OperationErrorType } from './errors/OperationError'
-import { Database } from './db/Database'
-import { generateRestHandlers } from './model/generateRestHandlers'
-import {
- generateGraphQLHandlers,
- generateGraphQLSchema,
-} from './model/generateGraphQLHandlers'
-import { sync } from './extensions/sync'
-
-/**
- * Create a database with the given models.
- */
-export function factory(
- dictionary: Dictionary,
-): FactoryAPI {
- const db = new Database(dictionary)
-
- // Initialize database extensions.
- sync(db)
-
- return Object.entries(dictionary).reduce(
- (acc, [modelName, props]) => {
- acc[modelName] = createModelApi(
- dictionary,
- modelName,
- props,
- db,
- )
- return acc
- },
- {
- [DATABASE_INSTANCE]: db,
- },
- )
-}
-
-function createModelApi<
- Dictionary extends ModelDictionary,
- ModelName extends string,
->(
- dictionary: Dictionary,
- modelName: ModelName,
- definition: ModelDefinition,
- db: Database,
-) {
- const parsedModel = parseModelDefinition(dictionary, modelName, definition)
- const { primaryKey } = parsedModel
-
- const api: ModelAPI = {
- create(initialValues = {}) {
- const entity = createModel(
- modelName,
- definition,
- dictionary,
- parsedModel,
- initialValues,
- db,
- )
-
- const entityId = entity[entity[PRIMARY_KEY]] as string
-
- if (!entityId) {
- throw new OperationError(
- OperationErrorType.MissingPrimaryKey,
- format(
- 'Failed to create a "%s" entity: expected the primary key "%s" to have a value, but got: %s',
- modelName,
- primaryKey,
- entityId,
- ),
- )
- }
-
- // Prevent creation of multiple entities with the same primary key value.
- if (db.has(modelName, entityId)) {
- throw new OperationError(
- OperationErrorType.DuplicatePrimaryKey,
- format(
- 'Failed to create a "%s" entity: an entity with the same primary key "%s" ("%s") already exists.',
- modelName,
- entityId,
- entity[PRIMARY_KEY],
- ),
- )
- }
-
- db.create(modelName, entity)
- return entity
- },
- count(query) {
- if (!query) {
- return db.count(modelName)
- }
-
- const results = executeQuery(modelName, primaryKey, query, db)
- return results.length
- },
- findFirst(query) {
- const results = executeQuery(modelName, primaryKey, query, db)
- const firstResult = first(results)
-
- if (query.strict && firstResult == null) {
- throw new OperationError(
- OperationErrorType.EntityNotFound,
- format(
- 'Failed to execute "findFirst" on the "%s" model: no entity found matching the query "%j".',
- modelName,
- query.where,
- ),
- )
- }
-
- return firstResult as Entity
- },
- findMany(query) {
- const results = executeQuery(modelName, primaryKey, query, db)
-
- if (results.length === 0 && query.strict) {
- throw new OperationError(
- OperationErrorType.EntityNotFound,
- format(
- 'Failed to execute "findMany" on the "%s" model: no entities found matching the query "%j".',
- modelName,
- query.where,
- ),
- )
- }
-
- return results
- },
- getAll() {
- return db.listEntities(modelName)
- },
- update({ strict, ...query }) {
- const results = executeQuery(modelName, primaryKey, query, db)
- const prevRecord = first(results)
-
- if (!prevRecord) {
- if (strict) {
- throw new OperationError(
- OperationErrorType.EntityNotFound,
- format(
- 'Failed to execute "update" on the "%s" model: no entity found matching the query "%j".',
- modelName,
- query.where,
- ),
- )
- }
-
- return null as any
- }
-
- const nextRecord = updateEntity(prevRecord, query.data, definition)
-
- if (
- nextRecord[prevRecord[PRIMARY_KEY]] !==
- prevRecord[prevRecord[PRIMARY_KEY]]
- ) {
- if (db.has(modelName, nextRecord[prevRecord[PRIMARY_KEY]])) {
- throw new OperationError(
- OperationErrorType.DuplicatePrimaryKey,
- format(
- 'Failed to execute "update" on the "%s" model: the entity with a primary key "%s" ("%s") already exists.',
- modelName,
- nextRecord[prevRecord[PRIMARY_KEY]],
- primaryKey,
- ),
- )
- }
- }
-
- db.update(modelName, prevRecord, nextRecord)
-
- return nextRecord
- },
- updateMany({ strict, ...query }) {
- const records = executeQuery(modelName, primaryKey, query, db)
- const updatedRecords: Entity[] = []
-
- if (records.length === 0) {
- if (strict) {
- throw new OperationError(
- OperationErrorType.EntityNotFound,
- format(
- 'Failed to execute "updateMany" on the "%s" model: no entities found matching the query "%j".',
- modelName,
- query.where,
- ),
- )
- }
-
- return null as any
- }
-
- records.forEach((prevRecord) => {
- const nextRecord = updateEntity(prevRecord, query.data, definition)
-
- if (
- nextRecord[prevRecord[PRIMARY_KEY]] !==
- prevRecord[prevRecord[PRIMARY_KEY]]
- ) {
- if (db.has(modelName, nextRecord[prevRecord[PRIMARY_KEY]])) {
- throw new OperationError(
- OperationErrorType.DuplicatePrimaryKey,
- format(
- 'Failed to execute "updateMany" on the "%s" model: the entity with a primary key "%s" ("%s") already exists.',
- modelName,
- nextRecord[prevRecord[PRIMARY_KEY]],
- primaryKey,
- ),
- )
- }
- }
-
- db.update(modelName, prevRecord, nextRecord)
- updatedRecords.push(nextRecord)
- })
-
- return updatedRecords
- },
- delete({ strict, ...query }) {
- const results = executeQuery(modelName, primaryKey, query, db)
- const record = first(results)
-
- if (!record) {
- if (strict) {
- throw new OperationError(
- OperationErrorType.EntityNotFound,
- format(
- 'Failed to execute "delete" on the "%s" model: no entity found matching the query "%o".',
- modelName,
- query.where,
- ),
- )
- }
-
- return null as any
- }
-
- db.delete(modelName, record[record[PRIMARY_KEY]] as string)
- return record
- },
- deleteMany({ strict, ...query }) {
- const records = executeQuery(modelName, primaryKey, query, db)
-
- if (records.length === 0) {
- if (strict) {
- throw new OperationError(
- OperationErrorType.EntityNotFound,
- format(
- 'Failed to execute "deleteMany" on the "%s" model: no entities found matching the query "%o".',
- modelName,
- query.where,
- ),
- )
- }
-
- return null as any
- }
-
- records.forEach((record) => {
- db.delete(modelName, record[record[PRIMARY_KEY]] as string)
- })
-
- return records
- },
- toHandlers(type: 'rest' | 'graphql', baseUrl: string): any {
- if (type === 'graphql') {
- return generateGraphQLHandlers(modelName, definition, api, baseUrl)
- }
-
- return generateRestHandlers(modelName, definition, api, baseUrl)
- },
- toGraphQLSchema() {
- return generateGraphQLSchema(modelName, definition, api)
- },
- }
-
- return api
-}
diff --git a/src/glossary.ts b/src/glossary.ts
deleted file mode 100644
index 63326aba..00000000
--- a/src/glossary.ts
+++ /dev/null
@@ -1,244 +0,0 @@
-import { GraphQLSchema } from 'graphql'
-import { GraphQLHandler, RestHandler } from 'msw'
-import { Database } from './db/Database'
-import { NullableProperty } from './nullable'
-import { PrimaryKey } from './primaryKey'
-import {
- BulkQueryOptions,
- QueryOptions,
- QuerySelector,
- WeakQuerySelector,
-} from './query/queryTypes'
-import { OneOf, ManyOf } from './relations/Relation'
-
-export const PRIMARY_KEY = Symbol('primaryKey')
-export const ENTITY_TYPE = Symbol('type')
-export const DATABASE_INSTANCE = Symbol('databaseInstance')
-
-export type KeyType = string | number | symbol
-export type AnyObject = Record
-export type PrimaryKeyType = string | number
-export type PrimitiveValueType = string | number | boolean | Date
-export type ModelValueType = PrimitiveValueType | PrimitiveValueType[]
-export type ModelValueTypeGetter = () => ModelValueType
-
-export type ModelDefinition = Record
-
-export type ModelDefinitionValue =
- | PrimaryKey
- | ModelValueTypeGetter
- | NullableProperty
- | OneOf
- | ManyOf
- | NestedModelDefinition
-
-export type NestedModelDefinition = {
- [propertyName: string]:
- | ModelValueTypeGetter
- | NullableProperty
- | OneOf
- | ManyOf
- | NestedModelDefinition
-}
-
-export type FactoryAPI> = {
- [ModelName in keyof Dictionary]: ModelAPI
-} & {
- [DATABASE_INSTANCE]: Database
-}
-
-export type ModelDictionary = Record>
-
-export type Limit = {
- [Key in keyof Definition]: Definition[Key] extends ModelDefinitionValue
- ? Definition[Key]
- : {
- error: 'expected primary key, initial value, or relation'
- }
-}
-
-export interface InternalEntityProperties {
- readonly [ENTITY_TYPE]: ModelName
- readonly [PRIMARY_KEY]: PrimaryKeyType
-}
-
-export type Entity<
- Dictionary extends ModelDictionary,
- ModelName extends keyof Dictionary,
-> = PublicEntity & InternalEntityProperties
-
-export type PublicEntity<
- Dictionary extends ModelDictionary,
- ModelName extends keyof Dictionary,
-> = Value
-
-export type RequiredExactlyOne<
- ObjectType,
- KeysType extends keyof ObjectType = keyof ObjectType,
-> = {
- [Key in KeysType]: Required> &
- Partial, never>>
-}[KeysType] &
- Pick>
-
-export type DeepRequiredExactlyOne =
- RequiredExactlyOne<{
- [Key in keyof Target]: Target[Key] extends AnyObject
- ? DeepRequiredExactlyOne
- : Target[Key]
- }>
-
-export type InitialValues<
- Dictionary extends ModelDictionary,
- ModelName extends keyof Dictionary,
-> = Partial>
-
-export type StrictQueryReturnType<
- Options extends QueryOptions,
- ValueType extends unknown,
-> = Options['strict'] extends true ? ValueType : ValueType | null
-
-export interface ModelAPI<
- Dictionary extends ModelDictionary,
- ModelName extends keyof Dictionary,
-> {
- /**
- * Create a single entity for the model.
- */
- create(
- initialValues?: InitialValues,
- ): Entity
- /**
- * Return the total number of entities.
- */
- count(
- query?: QueryOptions & QuerySelector>,
- ): number
- /**
- * Find a first entity matching the query.
- */
- findFirst(
- query: Options & QuerySelector>,
- ): StrictQueryReturnType>
- /**
- * Find multiple entities.
- */
- findMany(
- query: QueryOptions &
- WeakQuerySelector> &
- BulkQueryOptions>,
- ): Entity[]
- /**
- * Return all entities of the current model.
- */
- getAll(): Entity[]
- /**
- * Update a single entity with the next data.
- */
- update(
- query: Options &
- QuerySelector> & {
- data: Partial>
- },
- ): StrictQueryReturnType>
- /**
- * Update many entities with the next data.
- */
- updateMany(
- query: Options &
- QuerySelector> & {
- data: Partial>
- },
- ): StrictQueryReturnType[]>
- /**
- * Delete a single entity.
- */
- delete(
- query: Options & QuerySelector>,
- ): StrictQueryReturnType>
- /**
- * Delete multiple entities.
- */
- deleteMany(
- query: Options & QuerySelector>,
- ): StrictQueryReturnType[]>
- /**
- * Generate request handlers of the given type based on the model definition.
- */
- toHandlers(type: 'rest', baseUrl?: string): RestHandler[]
- /**
- * Generate request handlers of the given type based on the model definition.
- */
- toHandlers(type: 'graphql', baseUrl?: string): GraphQLHandler[]
-
- /**
- * Generate a graphql schema based on the model definition.
- */
- toGraphQLSchema(): GraphQLSchema
-}
-
-export type UpdateManyValue<
- Target extends AnyObject,
- Dictionary extends ModelDictionary,
- ModelRoot extends AnyObject = Target,
-> =
- | Value
- | {
- [Key in keyof Target]?: Target[Key] extends PrimaryKey
- ? (
- prevValue: ReturnType,
- entity: Value,
- ) => ReturnType
- : Target[Key] extends ModelValueTypeGetter
- ? (
- prevValue: ReturnType,
- entity: Value,
- ) => ReturnType
- : Target[Key] extends OneOf
- ? (
- prevValue: PublicEntity,
- entity: Value,
- ) => PublicEntity
- : Target[Key] extends ManyOf
- ? (
- prevValue: PublicEntity[],
- entity: Value,
- ) => PublicEntity[]
- : Target[Key] extends AnyObject
- ? Partial>
- : (
- prevValue: ReturnType,
- entity: Value,
- ) => ReturnType
- }
-
-export type Value<
- Target extends AnyObject,
- Dictionary extends ModelDictionary,
-> = {
- [Key in keyof Target]: Target[Key] extends PrimaryKey
- ? ReturnType
- : // Extract underlying value type of nullable properties
- Target[Key] extends NullableProperty
- ? ReturnType
- : // Extract value type from OneOf relations.
- Target[Key] extends OneOf
- ? Nullable extends true
- ? PublicEntity | null
- : PublicEntity | undefined
- : // Extract value type from ManyOf relations.
- Target[Key] extends ManyOf
- ? Nullable extends true
- ? PublicEntity 
+