Skip to content

Commit fdaea68

Browse files
hotlonghotlong
committed
Add Plugin protocol schemas and related documentation; update TypeScript definitions
1 parent 766e7de commit fdaea68

File tree

9 files changed

+284
-1
lines changed

9 files changed

+284
-1
lines changed

‎content/docs/references/system/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ This section contains all protocol schemas for the system layer of ObjectStack.
1818
<Card href="./job" title="Job" description="Source: packages/spec/src/system/job.zod.ts" />
1919
<Card href="./logger" title="Logger" description="Source: packages/spec/src/system/logger.zod.ts" />
2020
<Card href="./manifest" title="Manifest" description="Source: packages/spec/src/system/manifest.zod.ts" />
21+
<Card href="./plugin" title="Plugin" description="Source: packages/spec/src/system/plugin.zod.ts" />
2122
<Card href="./scoped-storage" title="Scoped Storage" description="Source: packages/spec/src/system/scoped-storage.zod.ts" />
2223
<Card href="./translation" title="Translation" description="Source: packages/spec/src/system/translation.zod.ts" />
2324
</Cards>

‎content/docs/references/system/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
"job",
1212
"logger",
1313
"manifest",
14+
"plugin",
1415
"scoped-storage",
1516
"translation"
1617
]

‎content/docs/references/system/plugin.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: Plugin
3+
description: Plugin protocol schemas
4+
---
5+
6+
# Plugin
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/system/plugin.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { PluginSchema, PluginContextSchema, PluginLifecycleSchema } from '@objectstack/spec/system';
16+
import type { Plugin, PluginContext, PluginLifecycle } from '@objectstack/spec/system';
17+
18+
// Validate data
19+
const result = PluginSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## Plugin
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **id** | `string` | ✅ | Unique Plugin ID (e.g. com.example.crm) |
31+
| **version** | `string` | ✅ | Semantic Version |
32+
| **description** | `string` | optional | |
33+
| **author** | `string` | optional | |
34+
| **homepage** | `string` | optional | |
35+
36+
---
37+
38+
## PluginContext
39+
40+
### Properties
41+
42+
| Property | Type | Required | Description |
43+
| :--- | :--- | :--- | :--- |
44+
| **ql** | `Record<string, any>` | ✅ | ObjectQL Engine Interface |
45+
| **os** | `Record<string, any>` | ✅ | ObjectStack Kernel Interface |
46+
| **logger** | `Record<string, any>` | ✅ | Logger Interface |
47+
| **storage** | `Record<string, any>` | ✅ | Storage Interface |
48+
| **i18n** | `Record<string, any>` | ✅ | Internationalization Interface |
49+
| **metadata** | `Record<string, any>` | ✅ | |
50+
| **events** | `Record<string, any>` | ✅ | |
51+
| **app** | `Record<string, any>` | ✅ | App Framework Interface |
52+
| **drivers** | `Record<string, any>` | ✅ | Driver Registry |
53+
54+
---
55+
56+
## PluginLifecycle
57+
58+
### Properties
59+
60+
| Property | Type | Required | Description |
61+
| :--- | :--- | :--- | :--- |
62+

‎packages/spec/json-schema/system/Plugin.json‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{
2+
"$ref": "#/definitions/Plugin",
3+
"definitions": {
4+
"Plugin": {
5+
"type": "object",
6+
"properties": {
7+
"id": {
8+
"type": "string",
9+
"minLength": 1,
10+
"description": "Unique Plugin ID (e.g. com.example.crm)"
11+
},
12+
"version": {
13+
"type": "string",
14+
"pattern": "^\\d+\\.\\d+\\.\\d+$",
15+
"description": "Semantic Version"
16+
},
17+
"description": {
18+
"type": "string"
19+
},
20+
"author": {
21+
"type": "string"
22+
},
23+
"homepage": {
24+
"type": "string",
25+
"format": "uri"
26+
}
27+
},
28+
"required": [
29+
"id",
30+
"version"
31+
],
32+
"additionalProperties": false
33+
}
34+
},
35+
"$schema": "http://json-schema.org/draft-07/schema#"
36+
}

‎packages/spec/json-schema/system/PluginContext.json‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
{
2+
"$ref": "#/definitions/PluginContext",
3+
"definitions": {
4+
"PluginContext": {
5+
"type": "object",
6+
"properties": {
7+
"ql": {
8+
"type": "object",
9+
"properties": {},
10+
"additionalProperties": true,
11+
"description": "ObjectQL Engine Interface"
12+
},
13+
"os": {
14+
"type": "object",
15+
"properties": {},
16+
"additionalProperties": true,
17+
"description": "ObjectStack Kernel Interface"
18+
},
19+
"logger": {
20+
"type": "object",
21+
"properties": {},
22+
"additionalProperties": true,
23+
"description": "Logger Interface"
24+
},
25+
"storage": {
26+
"type": "object",
27+
"properties": {},
28+
"additionalProperties": true,
29+
"description": "Storage Interface"
30+
},
31+
"i18n": {
32+
"type": "object",
33+
"properties": {},
34+
"additionalProperties": true,
35+
"description": "Internationalization Interface"
36+
},
37+
"metadata": {
38+
"type": "object",
39+
"additionalProperties": {}
40+
},
41+
"events": {
42+
"type": "object",
43+
"additionalProperties": {}
44+
},
45+
"app": {
46+
"type": "object",
47+
"properties": {
48+
"router": {
49+
"type": "object",
50+
"properties": {},
51+
"additionalProperties": true
52+
}
53+
},
54+
"required": [
55+
"router"
56+
],
57+
"additionalProperties": true,
58+
"description": "App Framework Interface"
59+
},
60+
"drivers": {
61+
"type": "object",
62+
"properties": {},
63+
"additionalProperties": true,
64+
"description": "Driver Registry"
65+
}
66+
},
67+
"required": [
68+
"ql",
69+
"os",
70+
"logger",
71+
"storage",
72+
"i18n",
73+
"metadata",
74+
"events",
75+
"app",
76+
"drivers"
77+
],
78+
"additionalProperties": false
79+
}
80+
},
81+
"$schema": "http://json-schema.org/draft-07/schema#"
82+
}

‎packages/spec/json-schema/system/PluginLifecycle.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"$ref": "#/definitions/PluginLifecycle",
3+
"definitions": {
4+
"PluginLifecycle": {
5+
"type": "object",
6+
"properties": {},
7+
"additionalProperties": false
8+
}
9+
},
10+
"$schema": "http://json-schema.org/draft-07/schema#"
11+
}

‎packages/spec/src/system/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ export * from './types';
1616

1717
// Re-export Core System Definitions
1818
export * from './manifest.zod';
19-
// export * from './plugin.zod'; // Moved to @objectstack/core
19+
export * from './plugin.zod';
2020
export * from './logger.zod';
2121
export * from './context.zod';
2222
export * from './scoped-storage.zod';

‎packages/spec/src/system/plugin.zod.ts‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
import { z } from 'zod';
2+
3+
// We use z.any() for services that are interfaces with methods,
4+
// as Zod cannot easily validate function signatures at runtime.
5+
export const PluginContextSchema = z.object({
6+
ql: z.object({
7+
object: z.function().returns(z.any()), // Return any to allow method chaining
8+
query: z.function().returns(z.any()),
9+
}).passthrough().describe('ObjectQL Engine Interface'),
10+
11+
os: z.object({
12+
getCurrentUser: z.function().returns(z.any()),
13+
getConfig: z.function().returns(z.any()),
14+
}).passthrough().describe('ObjectStack Kernel Interface'),
15+
16+
logger: z.object({
17+
debug: z.function().returns(z.void()),
18+
info: z.function().returns(z.void()),
19+
warn: z.function().returns(z.void()),
20+
error: z.function().returns(z.void()),
21+
}).passthrough().describe('Logger Interface'),
22+
23+
storage: z.object({
24+
get: z.function().returns(z.any()),
25+
set: z.function().returns(z.promise(z.void())),
26+
delete: z.function().returns(z.promise(z.void())),
27+
}).passthrough().describe('Storage Interface'),
28+
29+
i18n: z.object({
30+
t: z.function().returns(z.string()),
31+
getLocale: z.function().returns(z.string()),
32+
}).passthrough().describe('Internationalization Interface'),
33+
34+
metadata: z.record(z.any()),
35+
events: z.record(z.any()),
36+
37+
app: z.object({
38+
router: z.object({
39+
get: z.function().returns(z.any()),
40+
post: z.function().returns(z.any()),
41+
use: z.function().returns(z.any()),
42+
}).passthrough()
43+
}).passthrough().describe('App Framework Interface'),
44+
45+
drivers: z.object({
46+
register: z.function().returns(z.void()),
47+
}).passthrough().describe('Driver Registry'),
48+
});
49+
50+
export type PluginContextData = z.infer<typeof PluginContextSchema>;
51+
52+
export const PluginLifecycleSchema = z.object({
53+
onInstall: z.function()
54+
.args(PluginContextSchema)
55+
.returns(z.promise(z.void()))
56+
.optional(),
57+
58+
onEnable: z.function()
59+
.args(PluginContextSchema)
60+
.returns(z.promise(z.void()))
61+
.optional(),
62+
63+
onDisable: z.function()
64+
.args(PluginContextSchema)
65+
.returns(z.promise(z.void()))
66+
.optional(),
67+
68+
onUninstall: z.function()
69+
.args(PluginContextSchema)
70+
.returns(z.promise(z.void()))
71+
.optional(),
72+
73+
onUpgrade: z.function()
74+
.args(PluginContextSchema, z.string(), z.string())
75+
.returns(z.promise(z.void()))
76+
.optional(),
77+
});
78+
79+
export type PluginLifecycleHooks = z.infer<typeof PluginLifecycleSchema>;
80+
81+
export const PluginSchema = PluginLifecycleSchema.extend({
82+
id: z.string().min(1).describe('Unique Plugin ID (e.g. com.example.crm)'),
83+
version: z.string().regex(/^\d+\.\d+\.\d+$/).describe('Semantic Version'),
84+
description: z.string().optional(),
85+
author: z.string().optional(),
86+
homepage: z.string().url().optional(),
87+
});
88+
89+
export type PluginDefinition = z.infer<typeof PluginSchema>;

‎packages/types/tsconfig.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"extends": "../../tsconfig.json",
33
"include": ["src/**/*"],
4+
"exclude": ["node_modules", "dist"],
45
"compilerOptions": {
56
"outDir": "dist",
67
"rootDir": "src"

0 commit comments

Comments
 (0)