Skip to content

Commit 00b13e3

Browse files
CopilotCopilot
committed
Add comprehensive package reference documentation
1 parent 873cfd1 commit 00b13e3

1 file changed

Lines changed: 349 additions & 0 deletions

File tree

‎content/docs/references/packages.mdx‎

Lines changed: 349 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,349 @@
1+
---
2+
title: Package Reference
3+
description: Complete reference of all ObjectStack packages in the monorepo
4+
---
5+
6+
# Package Reference
7+
8+
ObjectStack is distributed as a monorepo containing **12 packages** organized into core packages and plugins.
9+
10+
## Package Overview
11+
12+
| Category | Count | Description |
13+
| :--- | :---: | :--- |
14+
| [Core Packages](#core-packages) | 9 | Essential runtime, protocols, and client SDKs |
15+
| [Plugin Packages](#plugin-packages) | 3 | Drivers and adapters for extending ObjectStack |
16+
17+
**Total: 12 packages**
18+
19+
---
20+
21+
## Core Packages
22+
23+
### @objectstack/spec
24+
25+
**Description:** ObjectStack Protocol & Specification - TypeScript Interfaces, JSON Schemas, and Convention Configurations
26+
27+
**Purpose:** The foundational package containing all protocol definitions and schemas. This is the "DNA" of ObjectStack.
28+
29+
**Key Exports:**
30+
- `Data` - Data protocol schemas (Field, Object, Query, etc.)
31+
- `UI` - UI protocol schemas (View, App, Dashboard, etc.)
32+
- `System` - System protocol schemas (Manifest, Plugin, Events, etc.)
33+
- `AI` - AI protocol schemas (Agent, RAG Pipeline, etc.)
34+
- `API` - API protocol schemas (Contract, Endpoint, etc.)
35+
- `Automation` - Automation protocol schemas (Flow, Workflow, etc.)
36+
- `Auth` - Authentication protocol schemas
37+
- `Permission` - Permission protocol schemas
38+
- `Hub` - Hub protocol schemas
39+
- `Integration` - Integration protocol schemas
40+
- `Shared` - Shared utilities and identifiers
41+
42+
**Protocol Count:** 109 Zod schemas
43+
44+
**Learn more:** [Protocol Reference](/docs/references)
45+
46+
---
47+
48+
### @objectstack/core
49+
50+
**Description:** Microkernel Core for ObjectStack
51+
52+
**Purpose:** Provides the runtime foundation for ObjectStack, including the plugin system, service registry, and logging infrastructure.
53+
54+
**Key Features:**
55+
- Plugin lifecycle management
56+
- Service registry for dependency injection
57+
- Structured logging system
58+
- Event bus for inter-plugin communication
59+
- Startup orchestration
60+
61+
**Use Cases:**
62+
- Building custom ObjectStack runtimes
63+
- Creating plugin-based architectures
64+
- Implementing microkernel patterns
65+
66+
---
67+
68+
### @objectstack/runtime
69+
70+
**Description:** ObjectStack Core Runtime & Query Engine
71+
72+
**Purpose:** The main runtime engine that executes ObjectQL queries and manages data operations.
73+
74+
**Key Features:**
75+
- Query execution engine
76+
- Data operation handlers (CRUD)
77+
- Runtime context management
78+
- Transaction support
79+
- Driver orchestration
80+
81+
**Use Cases:**
82+
- Running ObjectStack applications
83+
- Executing data queries
84+
- Managing database operations
85+
86+
---
87+
88+
### @objectstack/objectql
89+
90+
**Description:** Isomorphic ObjectQL Engine for ObjectStack
91+
92+
**Purpose:** Standalone ObjectQL query engine that can run in any JavaScript environment (Node.js, browsers, edge).
93+
94+
**Key Features:**
95+
- Isomorphic query execution (client and server)
96+
- ObjectQL AST parsing and compilation
97+
- Query optimization
98+
- Driver-agnostic query interface
99+
100+
**Use Cases:**
101+
- Client-side data querying
102+
- Edge function data access
103+
- Serverless query execution
104+
105+
---
106+
107+
### @objectstack/client
108+
109+
**Description:** Official Client SDK for ObjectStack Protocol
110+
111+
**Purpose:** Type-safe client library for interacting with ObjectStack APIs.
112+
113+
**Key Features:**
114+
- Type-safe API methods
115+
- Query builder interface
116+
- Authentication handling
117+
- Request/response transformation
118+
- Error handling
119+
120+
**Use Cases:**
121+
- Building frontend applications
122+
- Consuming ObjectStack APIs
123+
- Type-safe data fetching
124+
125+
---
126+
127+
### @objectstack/client-react
128+
129+
**Description:** React hooks for ObjectStack Client SDK
130+
131+
**Purpose:** React-specific hooks and components for ObjectStack integration.
132+
133+
**Requirements:** React 18+
134+
135+
**Key Features:**
136+
- `useQuery` - Data fetching hook
137+
- `useMutation` - Data mutation hook
138+
- `useObject` - Object metadata hook
139+
- React Query integration
140+
- Optimistic updates
141+
142+
**Use Cases:**
143+
- Building React applications
144+
- Real-time data synchronization
145+
- Form handling with ObjectStack data
146+
147+
---
148+
149+
### @objectstack/cli
150+
151+
**Description:** Command Line Interface for ObjectStack Protocol
152+
153+
**Purpose:** Developer tools for scaffolding, building, and managing ObjectStack applications.
154+
155+
**Commands:**
156+
- `os init` / `objectstack init` - Initialize new project
157+
- `os build` / `objectstack build` - Build and validate metadata
158+
- `os dev` / `objectstack dev` - Development server
159+
- `os generate` - Code generation from schemas
160+
161+
**Use Cases:**
162+
- Project scaffolding
163+
- Metadata validation
164+
- Development workflows
165+
- Code generation
166+
167+
---
168+
169+
### @objectstack/ai-bridge
170+
171+
**Description:** AI/ML integration bridge for ObjectStack
172+
173+
**Purpose:** Provides adapters and utilities for integrating AI/ML models with ObjectStack.
174+
175+
**Key Features:**
176+
- LLM provider adapters (OpenAI, Anthropic, etc.)
177+
- Model registry and routing
178+
- Token usage tracking
179+
- Embedding generation
180+
- RAG pipeline support
181+
182+
**Use Cases:**
183+
- Building AI-powered applications
184+
- Integrating LLMs with business data
185+
- Implementing RAG workflows
186+
187+
---
188+
189+
### @objectstack/types
190+
191+
**Description:** Shared interfaces describing the ObjectStack Runtime environment
192+
193+
**Purpose:** Common TypeScript type definitions used across all ObjectStack packages.
194+
195+
**Key Exports:**
196+
- `IKernel` - Kernel interface
197+
- `RuntimePlugin` - Plugin interface
198+
- Shared utility types
199+
- Runtime context types
200+
201+
**Use Cases:**
202+
- Plugin development
203+
- Type-safe integrations
204+
- Extending ObjectStack core
205+
206+
---
207+
208+
## Plugin Packages
209+
210+
### @objectstack/driver-memory
211+
212+
**Description:** In-Memory Driver for ObjectStack (Reference Implementation)
213+
214+
**Purpose:** A fully functional in-memory database driver used for testing and development.
215+
216+
**Key Features:**
217+
- Full ObjectQL support
218+
- Transaction support
219+
- Query execution
220+
- No external dependencies
221+
222+
**Use Cases:**
223+
- Testing ObjectStack applications
224+
- Development without database setup
225+
- Understanding driver implementation patterns
226+
227+
**Status:** Reference implementation for driver developers
228+
229+
---
230+
231+
### @objectstack/plugin-hono-server
232+
233+
**Description:** Standard Hono Server Adapter for ObjectStack Runtime
234+
235+
**Purpose:** HTTP server adapter using the Hono framework.
236+
237+
**Key Features:**
238+
- Fast HTTP server using Hono
239+
- REST API endpoints
240+
- Middleware support
241+
- Edge runtime compatible
242+
243+
**Use Cases:**
244+
- Production REST API deployment
245+
- Edge function hosting
246+
- Serverless deployments
247+
248+
---
249+
250+
### @objectstack/plugin-msw
251+
252+
**Description:** MSW (Mock Service Worker) Plugin for ObjectStack Runtime
253+
254+
**Purpose:** Testing plugin for mocking ObjectStack APIs in tests.
255+
256+
**Key Features:**
257+
- API mocking for tests
258+
- Request interception
259+
- Response simulation
260+
- Integration with MSW
261+
262+
**Use Cases:**
263+
- Unit testing
264+
- Integration testing
265+
- Frontend testing without backend
266+
267+
---
268+
269+
## Package Dependencies
270+
271+
### Dependency Graph
272+
273+
```
274+
@objectstack/spec (no dependencies)
275+
↓
276+
├─→ @objectstack/types
277+
├─→ @objectstack/core
278+
├─→ @objectstack/objectql
279+
├─→ @objectstack/runtime
280+
│ ↓
281+
│ └─→ @objectstack/client
282+
│ ↓
283+
│ └─→ @objectstack/client-react
284+
├─→ @objectstack/cli
285+
└─→ @objectstack/ai-bridge
286+
287+
Plugins (depend on core packages):
288+
├─→ @objectstack/driver-memory
289+
├─→ @objectstack/plugin-hono-server
290+
└─→ @objectstack/plugin-msw
291+
```
292+
293+
### Installation
294+
295+
**For Application Development:**
296+
```bash
297+
pnpm add @objectstack/runtime @objectstack/client
298+
```
299+
300+
**For React Applications:**
301+
```bash
302+
pnpm add @objectstack/client-react
303+
```
304+
305+
**For Plugin Development:**
306+
```bash
307+
pnpm add @objectstack/core @objectstack/spec
308+
```
309+
310+
**For CLI Tools:**
311+
```bash
312+
pnpm add -g @objectstack/cli
313+
```
314+
315+
---
316+
317+
## Version Compatibility
318+
319+
All packages in the monorepo are versioned together and released simultaneously to ensure compatibility.
320+
321+
**Current Version:** Check [CHANGELOG.md](https://github.com/objectstack-ai/spec/blob/main/CHANGELOG.md)
322+
323+
**Compatibility Matrix:**
324+
325+
| Package Version | Node.js | TypeScript | React (for client-react) |
326+
| :--- | :--- | :--- | :--- |
327+
| 0.6.x | ≥18.0.0 | ≥5.3.0 | ≥18.0.0 |
328+
329+
---
330+
331+
## Next Steps
332+
333+
<Cards>
334+
<Card
335+
href="/docs/references"
336+
title="Protocol Reference"
337+
description="Explore the 109 protocol schemas"
338+
/>
339+
<Card
340+
href="/docs/developers"
341+
title="Developer Guide"
342+
description="Build with ObjectStack packages"
343+
/>
344+
<Card
345+
href="https://github.com/objectstack-ai/spec"
346+
title="GitHub Repository"
347+
description="View source code and contribute"
348+
/>
349+
</Cards>

0 commit comments

Comments
 (0)