@objectstack/spec 0.1.2 → 0.3.0

package/README.md

@@ -44,12 +44,115 @@ The specification is divided into three protocols:
 
 ## 📚 Usage
 
+### Import Styles
+
+**Important:** This package does NOT export types at the root level to prevent naming conflicts. You must use one of the following import styles:
+
+#### 1. Namespace Imports from Root
+
+Import protocol namespaces from the package root:
+
+```typescript
+import { Data, UI, System, AI, API } from '@objectstack/spec';
+
+const field: Data.Field = {
+  name: 'task_name',
+  type: 'text',
+  label: 'Task Name',
+};
+
+const user: System.User = {
+  id: 'user_123',
+  email: 'user@example.com',
+  // ...
+};
+
+const agent: AI.Agent = {
+  name: 'sales_assistant',
+  // ...
+};
+```
+
+**Pros:**
+- Single import line for multiple protocols
+- Clear namespace boundaries
+- No naming conflicts
+
+#### 2. Namespace Imports via Subpath
+
+Import protocol domains individually:
+
+```typescript
+import * as Data from '@objectstack/spec/data';
+import * as UI from '@objectstack/spec/ui';
+import * as System from '@objectstack/spec/system';
+import * as AI from '@objectstack/spec/ai';
+import * as API from '@objectstack/spec/api';
+
+const field: Data.Field = {
+  name: 'task_name',
+  type: 'text',
+  label: 'Task Name',
+};
+
+const user: System.User = {
+  id: 'user_123',
+  email: 'user@example.com',
+  // ...
+};
+```
+
+**Pros:**
+- Explicit about which protocols are used
+- Better tree-shaking (only imports needed protocols)
+- Clear namespace boundaries
+
+#### 3. Direct Subpath Imports
+
+Import specific types from subpaths:
+
+```typescript
+import { Field, FieldType, ObjectSchema } from '@objectstack/spec/data';
+import { User, Session } from '@objectstack/spec/system';
+import { App, View } from '@objectstack/spec/ui';
+
+const field: Field = {
+  name: 'task_name',
+  type: 'text',
+  label: 'Task Name',
+};
+
+const user: User = {
+  id: 'user_123',
+  email: 'user@example.com',
+  // ...
+};
+```
+
+**Pros:**
+- Most concise syntax
+- Good for importing specific types
+- No namespace prefix needed
+
+**Cons:**
+- Need to know which subpath contains each type
+- Multiple import statements for different protocols
+
 ### Validation (Runtime)
 
 ```typescript
-import { ObjectSchema } from '@objectstack/spec';
+// Style 1: Namespace from root
+import { Data } from '@objectstack/spec';
+const result = Data.ObjectSchema.safeParse(userConfig);
+
+// Style 2: Namespace via subpath
+import * as Data from '@objectstack/spec/data';
+const result = Data.ObjectSchema.safeParse(userConfig);
 
+// Style 3: Direct subpath import
+import { ObjectSchema } from '@objectstack/spec/data';
 const result = ObjectSchema.safeParse(userConfig);
+
 if (!result.success) {
   console.error("Invalid Object definition", result.error);
 }
@@ -58,14 +161,33 @@ if (!result.success) {
 ### Type Definitions (Compile Time)
 
 ```typescript
-import type { Object, Field } from '@objectstack/spec';
+// Style 1: Namespace from root
+import type { Data } from '@objectstack/spec';
+const myField: Data.Field = {
+  name: "task_name",
+  type: "text",
+  label: "Task Name"
+};
 
-const myObject: Object = {
-  name: "project_task",
-  fields: { ... }
+// Style 2: Direct subpath import
+import type { Field } from '@objectstack/spec/data';
+const myField: Field = {
+  name: "task_name",
+  type: "text",
+  label: "Task Name"
 };
 ```
 
+Using namespace imports for multiple protocols:
+
+```typescript
+import type * as Data from '@objectstack/spec/data';
+import type * as System from '@objectstack/spec/system';
+
+const field: Data.Field = { /* ... */ };
+const user: System.User = { /* ... */ };
+```
+
 ### JSON Schema (Tooling)
 The package includes valid JSON Schemas in the `/json-schema` directory.
 These can be used with:

package/dist/ai/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AI Protocol Exports
+ *
+ * AI/ML Capabilities
+ * - Agent Configuration
+ * - Model Registry & Selection
+ * - RAG Pipeline
+ * - Natural Language Query (NLQ)
+ */
+export * from './agent.zod';
+export * from './model-registry.zod';
+export * from './rag-pipeline.zod';
+export * from './nlq.zod';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC"}

package/dist/ai/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * AI Protocol Exports
+ *
+ * AI/ML Capabilities
+ * - Agent Configuration
+ * - Model Registry & Selection
+ * - RAG Pipeline
+ * - Natural Language Query (NLQ)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./agent.zod"), exports);
+__exportStar(require("./model-registry.zod"), exports);
+__exportStar(require("./rag-pipeline.zod"), exports);
+__exportStar(require("./nlq.zod"), exports);