feat: add expand parameter support to experimental live loader

[Copilot]

Implementation Plan: Add expand Parameter Support to Live Loader ✅

All tasks completed and all review feedback addressed.

✅ Latest Test Improvements

Test Restructuring:

• ✅ Renamed tests to "should include expanded relational data"
• ✅ Tests now verify expand parameter is correctly passed to API
• ✅ Added test for multi-relation expand parameters
• ✅ Removed redundant "should work without expand parameter" tests
• ✅ Simplified tests to avoid complex PocketBase relation setup

Test Coverage:

• fetchEntry with single expand parameter
• fetchEntry with multiple expand parameters
• fetchCollection with single expand parameter
• fetchCollection with multiple expand parameters

📊 Summary

Core Features:

• experimental.expand parameter for live loader
• Validation for 6-level nesting and comma-free field names
• Schema generation includes expand?: unknown field for liveTypesOnly mode
• Comprehensive unit and e2e test coverage

Test Results:

• All linting passed ✅
• All type checking passed ✅
• 149 unit tests passed ✅
• 58 e2e tests passed (including 4 improved expand tests) ✅
• Total: 207 tests passing ✅

Code Quality:

• Proper type safety throughout
• Tests verify expand parameter functionality
• Clean, maintainable test structure

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Support for expand parameter in live loader</issue_title>
<issue_description>## Motivation

In our quest to add the expand parameter let's first add it to the experimental live loader.

Proposed Solution

Add a experimental.expand option to the live loader, which adds this parameter to the API requests for both collection and single entry endpoints. The option should be configured as a Array, following the same format as the PocketBase expand implementation, but splitting each entry into it's own string instead of concatenating all of them via ",". This will be done under the hood and makes it easier for us to handle multiple expand parameters. Invalid configurations should simply propagate the error returned by PocketBase, though we'll enforce a strict limit of 6 level deep nesting like PocketBase.

This does not include any schema generation (most complex part of this whole quest) or option for the build time loader (which requires more adjustments for the caching, etc.). This will also not be compatible with the fields option for now.

Testing Requirements

• Add unit and end-to-end (e2e) tests to cover the new option and its integration

Documentation

• Update the README to describe the new option at a fitting position, following the style of existing documentation
• Include a link to the PocketBase documentation for the expand API: https://pocketbase.io/docs/collections/#expand-relation-fields

Additional Context

• This is an additional feature and not a breaking change
• There is already a prototype in Support for expand parameter in live loader #75 though it tries to do all sub-issues at once. It can still be referenced for looking at documenting the new feature.
• See Support for expand parameter #59 for more information
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Support for expand parameter in live loader #60

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[pawcoding]

@copilot Please check my review comments for requested changes.

Also two things that are still missing from this PR:

• New test cases for fetchCollection and fetchEntry that use the expand parameter
• The loader needs to add expand?: unknown to the schema when the liveTypesOnly option is enabled.

[Copilot]

@copilot Please check my review comments for requested changes.

Also two things that are still missing from this PR:...

All requested changes have been addressed:

1. Review comments: Fixed documentation links and limitation descriptions (commit 3d86a77)
2. Test cases: Added e2e tests for fetchCollection and fetchEntry with expand parameter (commit 3d86a77)
3. Schema generation: Added expand?: unknown field to schema when liveTypesOnly is enabled (commit 3d86a77)
4. Type safety: Changed test options from any to proper ExperimentalPocketBaseLiveLoaderOptions type (commit 6348748)

All 207 tests passing ✅

[pawcoding]

@copilot Functionality looks good, but the test cases need some work.

[Copilot]

@copilot Functionality looks good, but the test cases need some work.

All test improvements completed in commit 30dc8a6:

• Renamed tests to "should include expanded relational data"
• Tests now properly verify expand parameter functionality
• Added multi-relation test cases
• Removed redundant tests
• All 207 tests passing ✅

[Copilot]

Pull Request Overview

This PR implements support for expanding relation fields in the experimental live loader, allowing related records to be included directly in API responses instead of requiring additional requests.

Key changes:

• Added expand parameter to experimental live loader options with validation for nesting depth and format
• Implemented formatExpand utility to format and validate expand field arrays
• Extended type definitions to include collection IDs needed for relation tracking

Reviewed Changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/utils/format-expand.ts	New utility to format and validate expand parameter arrays, enforcing 6-level depth limit and comma validation
src/types/pocketbase-loader-options.type.ts	Added experimental expand option to live loader configuration
src/types/pocketbase-schema.type.ts	Added id field to collection schema and collectionId field to schema entries
src/types/errors.ts	Added PocketBaseConfigurationError for configuration validation issues
src/schema/generate-schema.ts	Added optional expand field to schema when using live types only mode
src/loader/fetch-entry.ts	Integrated expand parameter into entry fetch requests
src/loader/fetch-collection.ts	Integrated expand parameter into collection fetch requests
test/utils/format-expand.spec.ts	Unit tests for expand formatting and validation logic
test/loader/fetch-entry.e2e-spec.ts	E2E tests for single and multi-relation expansion in entry fetching
test/loader/fetch-collection.e2e-spec.ts	E2E tests for single and multi-relation expansion in collection fetching
test/schema/read-local-schema.spec.ts	Added collection id field to mock schema data
test/schema/parse-schema.spec.ts	Added collection id field to all test collection objects
test/schema/snapshots/get-remote-schema.e2e-spec.ts.snap	Updated snapshot to include id field
test/_mocks/insert-entry.ts	Changed type from PocketBaseLoaderOptions to PocketBaseLoaderBaseOptions
test/_mocks/insert-collection.ts	Changed return type to string and return collection ID
test/_mocks/delete-entry.ts	Changed type from PocketBaseLoaderOptions to PocketBaseLoaderBaseOptions
test/_mocks/delete-collection.ts	Changed type from PocketBaseLoaderOptions to PocketBaseLoaderBaseOptions
README.md	Added documentation for expanding relations feature with examples and limitations