0.5 Alpha

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 24
+          node-version: 25
       - name: Install dependencies
         run: corepack enable && yarn
       - name: Run tests

.gitignore

@@ -11,6 +11,7 @@
 
 # Node dependencies
 node_modules
+packages/*/dist
 
 # npm-debug log
 npm-debug.*

.yarnrc.yml

@@ -1 +1,3 @@
+enableScripts: true
+
 nodeLinker: node-modules

AGENTS.md

@@ -0,0 +1,18 @@
+# TeamPlay Agent Notes
+
+TeamPlay is a full-stack signal ORM built on top of ShareDB. The main user-facing API is the object-tree signal model: `$`, `$.collection[id]`, `sub()`, `useSub()`, and `Signal<SchemaType>`.
+
+Before making nontrivial changes, read:
+
+- [architecture.md](./architecture.md) for the monorepo layout and runtime architecture.
+- [typing-architecture.md](./typing-architecture.md) for the TypeScript and generated type architecture.
+- [tasks.md](./tasks.md) for the current backlog, known priorities, and verification guidance. Treat it as context unless the user explicitly asks you to work through backlog items.
+
+Basic working rules:
+
+- Preserve public runtime APIs and the object-tree UX unless the user explicitly asks for a product change.
+- Prefer small, focused changes with nearby tests. Run focused tests while iterating and broader tests before commits.
+- Keep runtime behavior and TypeScript behavior aligned; update the architecture docs when the direction changes.
+- Do not invest in broad Compat rewrites. Compat is temporary; touch it only when needed to preserve behavior.
+- Work only in this project. Neighboring folders mentioned in old notes are not available in this environment.
+- The TS-authored packages (`teamplay`, `@teamplay/schema`, and `@teamplay/utils`) publish compiled `dist/` files but use the `teamplay-ts` export condition for source during development. When running hand-written Node checks against workspace packages, pass `-C teamplay-ts` (or `--conditions=teamplay-ts`) so Node resolves the current `src/` files instead of the generated `dist/` files.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

docs-theme/index.tsx

@@ -7,9 +7,9 @@ export * from '@rspress/core/theme-original'
 
 export function Layout () {
   return (
-    <div className="project-layout">
-      <ProjectSidebar activeProject="teamplay" />
-      <div className="project-layout-content">
+    <div className='project-layout'>
+      <ProjectSidebar activeProject='teamplay' />
+      <div className='project-layout-content'>
         <DefaultLayout />
       </div>
     </div>
@@ -58,16 +58,16 @@ interface ProjectSidebarProps {
 
 function ProjectSidebar ({ activeProject }: ProjectSidebarProps) {
   return (
-    <nav className="project-sidebar">
+    <nav className='project-sidebar'>
       {PROJECTS.map((project) => (
         <a
           key={project.id}
           href={project.url}
           className={`project-sidebar-button project-sidebar-button--${project.id} ${project.id === activeProject ? 'active' : ''}`}
           aria-label={project.name}
         >
-          <span className="project-sidebar-button__text">{project.label}</span>
-          <span className="project-sidebar-button__tooltip">{project.name}</span>
+          <span className='project-sidebar-button__text'>{project.label}</span>
+          <span className='project-sidebar-button__tooltip'>{project.name}</span>
         </a>
       ))}
     </nav>

docs/api/query-signals.md

@@ -18,6 +18,14 @@ A signal containing an array of IDs for the documents in the query result.
 const userIds = $activeUsers.ids.get()
 ```
 
+### extra
+
+A signal containing extra query metadata returned by the server, such as count metadata.
+
+```javascript
+const extra = $activeUsers.extra.get()
+```
+
 ### getIds()
 
 Returns an array of ids for the query results.
@@ -26,6 +34,8 @@ Returns an array of ids for the query results.
 const ids = $activeUsers.getIds()
 ```
 
+The result is always a `string[]`. Non-string ids are filtered out.
+
 ### map(callback)
 
 Maps over the documents in the query result.
@@ -64,4 +74,5 @@ for (const $user of $activeUsers) {
 
 - Query signals are reactive. Changes to the underlying data or to the query result will automatically update components using the query signal.
 - The documents within a query signal are themselves signals, allowing for nested reactivity.
- - For public documents in query results, `_id` is available in `get()` results and matches the document id.
+- For public documents in query results, `_id` is available in `get()` results and matches the document id.
+- `ids` and `extra` are reserved metadata properties on query signals. Use the collection path, such as `$.users['ids']`, when you need a document whose id has one of those names.

docs/api/root-signal.md

@@ -44,10 +44,34 @@ For convenience, TeamPlay allows you to access the private '_session' collection
 // These are equivalent:
 const $sessionData1 = $._session
 const $sessionData2 = $.session
+const $sessionData3 = $.$session
 ```
 
 This simplification makes it easier to work with session data without constantly typing the underscore.
 
+Private collections are client-local values, not database collections. They do not need `sub()` or `useSub()`, and they are not collection signals with `.add()`.
+
+If a private root collection has a schema, the schema describes the whole private value:
+
+```ts
+// models/_session/schema.ts
+import { defineSchema } from 'teamplay'
+
+export default defineSchema({
+  userId: { type: 'string' }
+})
+```
+
+After `teamplay-env.d.ts` is generated, all aliases share the same field types:
+
+```ts
+$._session.userId.get()
+$.session.userId.get()
+$.$session.userId.get()
+
+const { $userId } = $.session
+```
+
 ### Destructuring Assignment Simplification
 
 When destructuring properties from a signal object, TeamPlay provides a convenient shorthand for properties starting with '$'. The '$' is automatically removed from the property name:

docs/api/server-side.md

@@ -12,6 +12,24 @@ import { createBackend } from 'teamplay/server'
 const backend = createBackend()
 ```
 
+Common options:
+
+```ts
+const backend = createBackend({
+  validateSchema: true,
+  accessControl: true,
+  serverAggregate: true,
+  serverOnlyCollections: ['service']
+})
+```
+
+- `validateSchema`: validate public collection writes with registered schemas.
+- `accessControl`: enable access-control middleware for all collections. Collections without rules are denied by default.
+- `serverAggregate`: enable server-side aggregations.
+- `serverOnlyCollections`: collections that clients may not read or write through ShareDB.
+
+`serverOnlyCollections` forces the access middleware to initialize even when global `accessControl` is off. In that mode, only server-only collections and collections marked with `accessControl(..., { force: true })` are protected; all other collections keep the normal open behavior.
+
 ## initConnection(backend, options)
 
 Initializes the connection handler for WebSocket connections.

docs/api/signal-methods.md

@@ -10,6 +10,14 @@ Retrieves the current value of the signal.
 const value = $signal.get()
 ```
 
+## peek()
+
+Retrieves the current value without tracking it for reactive rendering.
+
+```javascript
+const value = $signal.peek()
+```
+
 ## set(value)
 
 Updates the value of the signal.
@@ -123,20 +131,26 @@ If both are provided, they must be equal, otherwise `add()` throws.
 
 ## getId()
 
-Returns the id for the current signal.
+Returns the usable string id for the document-like value represented by the current signal.
 
 ```javascript
 const id = $.users[userId].getId()
 ```
 
+For direct public document signals and query item signals, TeamPlay already knows the document id from the path and returns that id directly. For nested document-like values, private values, and aggregation rows, TeamPlay first checks string `_id` and `id` fields on the current value. If neither exists, it falls back to the string leaf segment of the signal path.
+
+If an explicit `_id` or `id` exists but is not a string, `getId()` returns `undefined`. The root signal and collection signals do not have ids and throw.
+
 ## getIds()
 
-Returns document ids for query or aggregation signals.
+Returns usable string ids for query or aggregation signals.
 
 ```javascript
 const ids = $activeUsers.getIds()
 ```
 
+For query signals, ids come from the subscribed query metadata. For aggregation signals, ids are read from each row's string `_id` or `id` field. Rows without a usable string id are omitted, so the result is always a `string[]`.
+
 ## getCollection()
 
 Returns the collection name for the signal.
@@ -162,6 +176,34 @@ Returns the last path segment as a string.
 const key = $.users[userId].leaf()
 ```
 
+## path()
+
+Returns the dot-separated path of the signal.
+
+```javascript
+const path = $.users[userId].name.path() // 'users.abc123.name'
+```
+
+## toString()
+
+Returns a debug label for the signal. Primitive string coercion uses only the path, while `toString()` includes the `Signal` label:
+
+```javascript
+String($.users[userId].name)                      // 'users.abc123.name'
+$.users[userId].name.toString()                   // '[Signal users.abc123.name]'
+Object.prototype.toString.call($.users[userId])   // '[object Signal]'
+```
+
+## getAssociations()
+
+Returns association metadata registered on the signal's model class.
+
+```javascript
+const associations = $.users[userId].getAssociations()
+```
+
+This is mostly useful for model-integration libraries and legacy ORM compatibility helpers.
+
 ## assign(object)
 
 Assigns multiple properties to a signal at once. This method iterates through the object's own properties and sets or deletes them on the signal.

docs/guide/installation.mdx

@@ -8,9 +8,9 @@ TeamPlay can run in three different modes. Pick the one that matches your needs
 
 ## Modes
 
-- **In-memory (default)**: in-memory only, no server, no persistence across reloads.
+- **In-memory Mode (default)**: in-memory only, no server, no persistence across reloads.
 - **Offline Mode**: client-only with local persistence (browser or React Native), no server.
-- **Server Sync**: real-time synchronization with a backend server.
+- **Server Sync Mode**: real-time synchronization with a backend server.
 
 ## In-memory Mode
 
@@ -27,22 +27,17 @@ await connect()
 
 See [Offline Mode](/guide/offline-mode) for details and React Native setup.
 
-## Synchronization with Server
+## Server Sync Mode
 
-To enable synchronization with the server, follow these steps:
-
-### Client Setup
-
-Enable the connection on the client somewhere early in your client app:
+To sync data with a server, connect from the client somewhere early in your app startup:
 
 ```js
 import connect from 'teamplay/connect'
+
 await connect()
 ```
 
-### Server Setup
-
-On the server, you need to create the TeamPlay backend and then create a connection handler for WebSockets:
+On the server, create the TeamPlay backend and attach its WebSocket upgrade handler to your Node HTTP server:
 
 ```js
 import { createBackend, initConnection } from 'teamplay/server'
@@ -52,17 +47,29 @@ const { upgrade } = initConnection(backend)
 server.on('upgrade', upgrade) // Node's 'http' server instance
 ```
 
-## Database Configuration
+## Production Setup
+
+For development, no extra database setup is needed. If `MONGO_URL` is not set, TeamPlay stores server data in an SQLite file named `local.db` in the root of your project.
+
+You can still write MongoDB-style queries and aggregations in this local setup. TeamPlay emulates that query behavior with [`mingo`](https://github.com/kofrasa/mingo).
+
+For production, configure the services your deployment needs:
+
+- `MONGO_URL`: use [MongoDB](https://mongodb.com) instead of the local SQLite file.
+- `REDIS_URL`: required when you run multiple server instances, so real-time updates can be coordinated through [Redis](https://redis.io).
+
+:::note
+TeamPlay's `createBackend()` is a wrapper around creating a [ShareDB backend](https://share.github.io/sharedb/api/backend). If you need lower-level control, you can create a ShareDB backend yourself and pass it to `initConnection()`. `ShareDB` is re-exported from `teamplay/server`, so you can import it as `import { ShareDB } from 'teamplay/server'`.
+:::
 
-By default no extra database setup is needed and the data is gonna be saved into an SQLite file `local.db` in the root of your project.
+## Optional ORM Setup
 
-You can still use the MongoDB query syntax with aggregations which is emulated using [`mingo`](https://github.com/kofrasa/mingo).
+TeamPlay works without an ORM setup: you can use signals, subscriptions, and real-time sync directly. When your app starts to have named collections such as users, games, orders, or events, the ORM gives you a conventional place to define document schemas, model methods, access rules, and server aggregations.
 
-- For production use, it's recommended to use [MongoDB](https://mongodb.com). It will be automatically used if you set the environment variable `MONGO_URL`.
-- When deploying to a cluster with multiple instances, you also have to provide the environment variable `REDIS_URL` ([Redis](https://redis.io)).
+To use the full ORM features, follow the [ORM Quick Start](/orm/index#quick-start). It shows the extra setup for the `models/` folder, the Babel plugin, and the shared `models.setup.ts` file used by both client and server.
 
 :::note
-TeamPlay's `createBackend()` is a wrapper around creating a [ShareDB's backend](https://share.github.io/sharedb/api/backend). You can instead manually create a ShareDB backend yourself and pass it to `initConnection()`. `ShareDB` is re-exported from `teamplay/server`, you can get it as `import { ShareDB } from 'teamplay/server'`.
+StartupJS apps can skip the manual ORM setup. StartupJS configures model loading and initializes TeamPlay models automatically.
 :::
 
 Now that you have TeamPlay installed and configured, you're ready to start using it in your application!