Skip to content

Commit 3be9b02

Browse files
hotlonghotlong
committed
Revise getting started docs and add VS Code extension recommendations
Updated README and documentation to emphasize YAML-based metadata, improved quick start instructions, and highlighted the importance of the ObjectQL VS Code extension. Added .vscode/extensions.json files to example projects to recommend relevant extensions for better developer experience.
1 parent 09b9957 commit 3be9b02

File tree

6 files changed

+110
-89
lines changed

6 files changed

+110
-89
lines changed

‎README.md‎

Lines changed: 32 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -45,82 +45,54 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi
4545

4646
## ⚡ Quick Start
4747

48-
### 0. Use the Generator (Recommended)
48+
### 1. Create a New Project
4949

5050
The fastest way to start is using the CLI to scaffold a new project.
5151

5252
```bash
53-
# Create a new project
53+
# Generate a new project
5454
npm create @objectql@latest my-app
5555

56-
# Choose a template when prompted (hello-world or starter)
56+
# Choose 'starter' for a complete example or 'hello-world' for minimal setup
5757
```
5858

59-
### 1. Manual Installation
59+
### 2. Install VS Code Extension (Critical 🚨)
6060

61-
If you prefer to install manually:
61+
For the best experience, install the official extension. It provides **Intelligent IntelliSense** and **Real-time Validation** for your YAML models.
6262

63-
```bash
64-
# Install core and a driver (e.g., Postgres or SQLite)
65-
npm install @objectql/core @objectql/driver-sql sqlite3
66-
```
63+
* Search for **"ObjectQL"** in the VS Code Marketplace.
64+
* Or open your new project, and VS Code will recommend it automatically via `.vscode/extensions.json`.
6765

68-
### 2. The Universal Script
66+
### 3. Define Metadata (The "Object")
6967

70-
ObjectQL can run in a single file without complex configuration.
68+
ObjectQL uses **YAML** as the source of truth. Create a file `src/objects/story.object.yml`:
7169

72-
```typescript
73-
import { ObjectQL } from '@objectql/core';
74-
import { SqlDriver } from '@objectql/driver-sql';
75-
76-
async function main() {
77-
// 1. Initialize Driver (In-Memory SQLite)
78-
const driver = new SqlDriver({
79-
client: 'sqlite3',
80-
connection: { filename: ':memory:' },
81-
useNullAsDefault: true
82-
});
83-
84-
// 2. Initialize Engine
85-
const app = new ObjectQL({
86-
datasources: { default: driver }
87-
});
88-
89-
// 3. Define Schema (The "Object")
90-
// In a real app, this would be loaded from a .yml file
91-
app.registerObject({
92-
name: "users",
93-
fields: {
94-
name: { type: "text", required: true },
95-
email: { type: "email", unique: true },
96-
role: {
97-
type: "select",
98-
options: ["admin", "user"],
99-
defaultValue: "user"
100-
}
101-
}
102-
});
103-
104-
await app.init();
105-
106-
// 4. Enjoy Type-Safe(ish) CRUD
107-
const ctx = app.createContext({ isSystem: true });
108-
const repo = ctx.object('users');
109-
110-
// Create
111-
await repo.create({ name: 'Alice', email: 'alice@example.com' });
112-
113-
// Find
114-
const users = await repo.find({
115-
filters: [['role', '=', 'user']]
116-
});
117-
118-
console.log(users);
119-
}
70+
```yaml
71+
name: story
72+
label: User Story
73+
fields:
74+
title:
75+
type: text
76+
required: true
77+
status:
78+
type: select
79+
options: [draft, active, done]
80+
default: draft
81+
points:
82+
type: number
83+
scale: 0
84+
default: 1
85+
```
86+
87+
### 4. Run & Play
88+
89+
Start the development server. ObjectQL will automatically load your YAML files and generate the database schema.
12090
121-
main();
91+
```bash
92+
npm run dev
12293
```
12394

95+
12496
---
12597

12698
## 🔌 The Driver Ecosystem

‎docs/guide/getting-started.md‎

Lines changed: 40 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,22 +26,51 @@ npm create @objectql@latest my-app -- --template hello-world
2626

2727
This will create a new project with all necessary dependencies.
2828

29-
### 2. Standard Setup (Project Tracker)
29+
### 2. Install VS Code Extension (Recommended) 🚨
30+
31+
To treat your metadata like code (with validation and autocomplete), install the **Standard ObjectStack AI Extension**.
32+
33+
1. Open Visual Studio Code.
34+
2. Go to the **Extensions** view (`Cmd+Shift+X`).
35+
3. Search for `ObjectQL` and install.
36+
4. Alternatively, when you open the created project, VS Code will prompt you to install recommended extensions.
37+
38+
> **Why?** The extension understands your `*.object.yml` files, validating field types and relationships in real-time, just like TypeScript.
39+
40+
### 3. Define the Protocol (Your Meta-Schema)
41+
42+
Instead of passing objects to a constructor, we define them in YAML. This is the "AI-Native" way—separate the **Instruction** (YAML) from the **Execution** (Runtime).
43+
44+
Create a file `src/objects/todo.object.yml`:
45+
46+
```yaml
47+
name: todo
48+
label: Task
49+
fields:
50+
title:
51+
type: text
52+
required: true
53+
searchable: true
54+
completed:
55+
type: boolean
56+
default: false
57+
priority:
58+
type: select
59+
options: [low, medium, high]
60+
default: medium
61+
```
3062
31-
For building real applications, use the `showcase` template. This sets up a proper folder structure with YAML metadata, TypeScript logic hooks, and relationship management.
63+
### 4. Run the Project
3264
3365
```bash
34-
npm create @objectql@latest project-tracker -- --template showcase
66+
npm run dev
3567
```
3668

37-
This structure follows our **Best Practices**:
38-
* **`src/objects/*.object.yml`**: Data definitions.
39-
* **`src/hooks/*.hook.ts`**: Business logic.
40-
* **`src/index.ts`**: Application entry point.
69+
ObjectQL will detect the new file, generate the necessary database tables (in SQLite by default), and start the server.
4170

42-
## Manual Setup (The Hard Way)
71+
### 5. Manual Setup (Programmatic API)
4372

44-
If you prefer to set up manually or add ObjectQL to an existing project:
73+
If you are integrating ObjectQL into an existing specialized backend (like a Lambda function or a custom script), you can use the Programmatic API.
4574

4675
```typescript
4776
import { ObjectQL } from '@objectql/core';
@@ -61,6 +90,7 @@ async function main() {
6190
});
6291

6392
// 3. Define Metadata Inline (Code as Configuration)
93+
// Note: We recommend YAML for scalability, but this works for scripts.
6494
app.registerObject({
6595
name: 'todo',
6696
fields: {
@@ -87,7 +117,7 @@ main();
87117

88118
## Scaling Up: The Metadata Approach
89119

90-
Once you are comfortable with the core, you should move your definitions to YAML files.
120+
Once you are comfortable with the basics, notice that standard projects use file-based modules configuration.
91121

92122
```typescript
93123
import { ObjectQL } from '@objectql/core';

‎docs/tutorials/task-manager.md‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -17,27 +17,25 @@ npm install @objectql/core @objectql/server @objectql/driver-sql sqlite3 tsx
1717

1818
## 2. Define Your Schema
1919

20-
Create a file named `project.object.yml`:
20+
Create a file named `src/objects/task.object.yml`:
2121

2222
```yaml
23-
name: project
24-
objects:
25-
task:
26-
label: Task
27-
fields:
28-
title:
29-
type: text
30-
required: true
31-
completed:
32-
type: boolean
33-
default: false
34-
priority:
35-
type: select
36-
options:
37-
- label: Low
38-
value: low
39-
- label: High
40-
value: high
23+
name: task
24+
label: Task
25+
fields:
26+
title:
27+
type: text
28+
required: true
29+
completed:
30+
type: boolean
31+
default: false
32+
priority:
33+
type: select
34+
options:
35+
- label: Low
36+
value: low
37+
- label: High
38+
value: high
4139
```
4240
4341
## 3. Start the Server

‎examples/quickstart/hello-world/.vscode/extensions.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"recommendations": [
3+
"objectstack-ai.vscode-objectql",
4+
"redhat.vscode-yaml",
5+
"dbaeumer.vscode-eslint"
6+
]
7+
}

‎examples/showcase/enterprise-erp/.vscode/extensions.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"recommendations": [
3+
"objectstack-ai.vscode-objectql",
4+
"redhat.vscode-yaml",
5+
"dbaeumer.vscode-eslint"
6+
]
7+
}

‎examples/showcase/project-tracker/.vscode/extensions.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"recommendations": [
3+
"objectstack-ai.vscode-objectql",
4+
"redhat.vscode-yaml",
5+
"dbaeumer.vscode-eslint"
6+
]
7+
}

0 commit comments

Comments
 (0)