{"_id":"@adfharrison1/go-db-typescript-sdk","_rev":"2-451fbbe81dabb9d733135822003e4957","name":"@adfharrison1/go-db-typescript-sdk","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@adfharrison1/go-db-typescript-sdk","version":"1.0.0","keywords":["database","document","api","typescript","sdk","go-db"],"author":{"name":"go-db team"},"license":"MIT","_id":"@adfharrison1/go-db-typescript-sdk@1.0.0","maintainers":[{"name":"adfharrison1","email":"alan.harrison.divided@hotmail.co.uk"}],"dist":{"shasum":"2b167bc0cf5b0783202d3fe35c4fc31f01406c0b","tarball":"https://registry.npmjs.org/@adfharrison1/go-db-typescript-sdk/-/go-db-typescript-sdk-1.0.0.tgz","fileCount":16,"integrity":"sha512-12emcaRptdLVluMHwMVzwXVhIFw0UR23EKpxfD/AoIfP8lqZW3/9HNl1aW/sQ8U35/gkjc0TrsX0XfXv9lSl6A==","signatures":[{"sig":"MEUCIByj6BvLvYHIq8zrSmjfFx9yShF7pWTFIJXZMsKuc2vnAiEA8J98XPMLoA77DBo6RamqKJJ2t5GYDdH3SkfAk7xaiiM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48986},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"dev":"tsc --watch","test":"jest","build":"tsc","clean":"rm -rf dist","test:ci":"jest --ci --coverage --watchAll=false","prepublish":"yarn test:ci && yarn build","test:watch":"jest --watch","publish:beta":"yarn prepublish && npm publish --tag beta --access public","check:publish":"npm pack --dry-run","publish:major":"yarn version:major && yarn publish --access public","publish:minor":"yarn version:minor && yarn publish --access public","publish:patch":"yarn version:patch && yarn publish --access public","test:coverage":"jest --coverage","version:major":"npm version major","version:minor":"npm version minor","version:patch":"npm version patch","prepublishOnly":"yarn clean && yarn build","publish:latest":"yarn prepublish && npm publish --access public","publish:script":"./scripts/publish.sh","publish:dry-run":"yarn prepublish && npm publish --dry-run --access public"},"_npmUser":{"name":"adfharrison1","email":"alan.harrison.divided@hotmail.co.uk"},"repository":{"url":"https://github.com/adfharrison1/go-db.git","type":"git","directory":"SDKs/typescript"},"description":"TypeScript SDK for go-db document database API","directories":{},"dependencies":{"axios":"^1.6.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.1.3","ts-jest":"^29.4.4","typescript":"^5.9.2","@types/jest":"^30.0.0","@types/node":"^24.5.2","testcontainers":"^11.6.0"},"_npmOperationalInternal":{"tmp":"tmp/go-db-typescript-sdk_1.0.0_1761398706049_0.15688030557958865","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@adfharrison1/go-db-typescript-sdk","version":"1.0.1","description":"TypeScript SDK for go-db document database API","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","clean":"rm -rf dist","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","test:ci":"jest --ci --coverage --watchAll=false","prepublishOnly":"yarn clean && yarn build","prepublish":"yarn test:ci && yarn build","scan:secrets":"./scripts/scan-secrets.sh","prepublish:safe":"yarn scan:secrets && yarn test:ci && yarn build","version:patch":"npm version patch","version:minor":"npm version minor","version:major":"npm version major","publish:patch":"yarn version:patch && yarn publish --access public","publish:minor":"yarn version:minor && yarn publish --access public","publish:major":"yarn version:major && yarn publish --access public","publish:dry-run":"yarn prepublish:safe && npm publish --dry-run --access public","publish:latest":"yarn prepublish:safe && npm publish --access public","publish:beta":"yarn prepublish:safe && npm publish --tag beta --access public","check:publish":"npm pack --dry-run","publish:script":"./scripts/publish.sh"},"keywords":["database","document","api","typescript","sdk","go-db"],"author":{"name":"go-db team"},"license":"MIT","devDependencies":{"@types/jest":"^30.0.0","@types/node":"^24.5.2","jest":"^30.1.3","testcontainers":"^11.6.0","ts-jest":"^29.4.4","typescript":"^5.9.2"},"dependencies":{"axios":"^1.6.0"},"repository":{"type":"git","url":"https://github.com/adfharrison1/go-db.git","directory":"SDKs/typescript"},"publishConfig":{"registry":"https://registry.npmjs.org/","access":"public"},"_id":"@adfharrison1/go-db-typescript-sdk@1.0.1","dist":{"shasum":"9b9c4e1d69e58c09dc34e42c5d35ba45000e6f1d","integrity":"sha512-X2WzlrneCmxypZtCRaYZHnDJVlHYsBcrfYzF/Qq8qz4+d8yB20ccI/v6U+m04r3dQkRwa/S8Duzp0Dg/YxIH3g==","tarball":"https://registry.npmjs.org/@adfharrison1/go-db-typescript-sdk/-/go-db-typescript-sdk-1.0.1.tgz","fileCount":16,"unpackedSize":49202,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFW/bItOgrXfNVuBUBbbyw43Q+GpG5s4ss1ASpSAsJHyAiAR1jTu19cPkG5rXZbsAncRT1ANgA/6ql+5AN4oTiMqpg=="}]},"_npmUser":{"name":"adfharrison1","email":"alan.harrison.divided@hotmail.co.uk"},"directories":{},"maintainers":[{"name":"adfharrison1","email":"alan.harrison.divided@hotmail.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/go-db-typescript-sdk_1.0.1_1761399766509_0.5220195777429786"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-25T13:25:05.947Z","modified":"2025-10-25T13:42:46.919Z","1.0.0":"2025-10-25T13:25:06.230Z","1.0.1":"2025-10-25T13:42:46.712Z"},"author":{"name":"go-db team"},"license":"MIT","keywords":["database","document","api","typescript","sdk","go-db"],"repository":{"type":"git","url":"https://github.com/adfharrison1/go-db.git","directory":"SDKs/typescript"},"description":"TypeScript SDK for go-db document database API","maintainers":[{"name":"adfharrison1","email":"alan.harrison.divided@hotmail.co.uk"}],"readme":"# go-db TypeScript SDK\n\nA **type-safe** TypeScript SDK for the go-db document database API. Define your data schemas once and get full type inference, compile-time validation, and intelligent autocomplete for all database operations.\n\n## ✨ Key Features\n\n- 🎯 **Fully Type-Safe**: Define your schema once, get type safety everywhere\n- 🚀 **Zero Runtime Cost**: Types disappear at compile time, zero performance overhead\n- 🔍 **Intelligent Autocomplete**: IDE knows your collections and fields\n- ⚡ **Compile-Time Validation**: Catch errors before they reach production\n- 📦 **Zero Dependencies**: Built on top of axios for HTTP requests\n- 🔄 **Batch Operations**: Efficient bulk insert and update operations\n- 🌊 **Streaming Support**: Handle large result sets efficiently\n\n## 🚀 Quick Start\n\n### 1. Install\n\n```bash\nyarn add @adfharrison1/go-db-typescript-sdk\n# or\nnpm install @adfharrison1/go-db-typescript-sdk\n```\n\n### 2. Define Your Schema\n\n```typescript\nimport { createClient } from '@adfharrison1/go-db-typescript-sdk';\n\n// Define your application's data types\ntype User = {\n  _id?: string; // Auto-generated by database\n  name: string;\n  age: number;\n  email: string;\n  active: boolean;\n  profile?: {\n    bio: string;\n    location: string;\n  };\n};\n\ntype Product = {\n  _id?: string; // Auto-generated by database\n  title: string;\n  price: number;\n  category: string;\n  inStock: boolean;\n};\n\n// Define your database schema\ntype MySchema = {\n  users: User;\n  products: Product;\n};\n\n// Create a type-safe client\nconst db = createClient<MySchema>({\n  baseURL: 'http://localhost:8080',\n  timeout: 30000,\n});\n```\n\n### 3. Enjoy Full Type Safety\n\n```typescript\n// ✅ TypeScript knows the exact structure\nconst user = await db.insert('users', {\n  name: 'John Doe', // ✅ Must be string\n  age: 30, // ✅ Must be number\n  email: 'john@example.com', // ✅ Must be string\n  active: true, // ✅ Must be boolean\n  profile: {\n    // ✅ Optional nested object\n    bio: 'Developer',\n    location: 'SF',\n  },\n});\n\n// ✅ TypeScript knows user is User & { _id: string }\nconsole.log(user._id); // Auto-generated ID\n\n// ✅ Type-safe queries with filters\nconst activeUsers = await db.find('users', {\n  where: {\n    active: true, // ✅ TypeScript knows this should be boolean\n    age: 25, // ✅ TypeScript knows this should be number\n  },\n  select: ['name', 'email'] as const, // ✅ Only valid field names\n  limit: 10,\n});\n\n// ✅ TypeScript knows activeUsers is Array<Pick<User, 'name' | 'email'>>\nactiveUsers.forEach((u) => {\n  console.log(`${u.name}: ${u.email}`); // ✅ Full type safety\n  // u.age would cause TypeScript error - not selected!\n});\n```\n\n## 🎯 Type-Safe Operations\n\n### Document CRUD\n\n```typescript\n// Insert - TypeScript enforces correct structure\nconst user = await db.insert('users', {\n  name: 'Jane Smith',\n  age: 28,\n  email: 'jane@example.com',\n  active: true,\n});\n\n// Get by ID - Returns User | null\nconst found = await db.getById('users', user._id!);\n\n// Update - Only valid fields and types allowed\nconst updated = await db.updateById('users', user._id!, {\n  age: 29, // ✅ TypeScript knows this should be number\n  active: false, // ✅ TypeScript knows this should be boolean\n});\n\n// Delete\nawait db.deleteById('users', user._id!);\n```\n\n### Type-Safe Queries\n\n```typescript\n// Find with filters - TypeScript validates field names and types\nconst results = await db.find('users', {\n  where: {\n    active: true, // ✅ Must be boolean\n    age: { $gte: 18 }, // ✅ Must be number\n    email: 'john@example.com', // ✅ Must be string\n  },\n  select: ['name', 'email', 'age'] as const, // ✅ Only valid fields\n  limit: 10,\n});\n\n// TypeScript knows results is Array<Pick<User, 'name' | 'email' | 'age'>>\n```\n\n### Batch Operations\n\n```typescript\n// Batch insert - Type-safe document arrays\nconst users = await db.batchInsert('users', [\n  { name: 'User 1', age: 25, email: 'user1@example.com', active: true },\n  { name: 'User 2', age: 30, email: 'user2@example.com', active: false },\n]);\n\n// Batch update - Type-safe operations\nawait db.batchUpdate('users', [\n  { id: users.documents[0]._id!, updates: { active: false } },\n  { id: users.documents[1]._id!, updates: { age: 31 } },\n]);\n```\n\n### Indexing\n\n```typescript\n// Create indexes - TypeScript validates field names\nawait db.createIndex('users', 'email'); // ✅ Valid field\nawait db.createIndex('users', 'age'); // ✅ Valid field\n// await db.createIndex('users', 'invalid'); // ❌ TypeScript error!\n\n// List indexes\nconst indexes = await db.getIndexes('users');\nconsole.log(indexes.indexes); // ['_id', 'email', 'age']\n```\n\n## 🔒 Compile-Time Validation\n\nTypeScript catches errors at compile time:\n\n```typescript\n// ❌ Invalid collection name\nawait db.getById('invalid_collection', 'id'); // TypeScript error!\n\n// ❌ Invalid field in insert\nawait db.insert('users', {\n  name: 'John',\n  invalidField: 'value', // TypeScript error!\n});\n\n// ❌ Wrong type for field\nawait db.insert('users', {\n  name: 'John',\n  age: 'thirty', // TypeScript error - should be number!\n});\n\n// ❌ Invalid field in select\nawait db.find('users', {\n  select: ['name', 'invalid_field'], // TypeScript error!\n});\n\n// ❌ Invalid field in where clause\nawait db.find('users', {\n  where: {\n    invalidField: 'value', // TypeScript error!\n  },\n});\n\n// ❌ Wrong type in where clause\nawait db.find('users', {\n  where: {\n    age: 'old', // TypeScript error - should be number!\n  },\n});\n```\n\n## 🏗️ Advanced Usage\n\n### Complex Schemas\n\n```typescript\ntype Order = {\n  _id?: string;\n  userId: string;\n  total: number;\n  status: 'pending' | 'completed' | 'cancelled';\n  items: Array<{\n    productId: string;\n    quantity: number;\n    price: number;\n  }>;\n  createdAt: string;\n  metadata?: {\n    notes: string;\n    priority: 'low' | 'medium' | 'high';\n  };\n};\n\ntype MySchema = {\n  users: User;\n  products: Product;\n  orders: Order;\n};\n\nconst db = createClient<MySchema>({ baseURL: 'http://localhost:8080' });\n\n// Full type safety for complex operations\nconst order = await db.insert('orders', {\n  userId: user._id!,\n  total: 99.99,\n  status: 'pending', // ✅ Must be one of the allowed values\n  items: [\n    {\n      productId: product._id!,\n      quantity: 1,\n      price: 99.99,\n    },\n  ],\n  createdAt: new Date().toISOString(),\n  metadata: {\n    notes: 'Rush order',\n    priority: 'high', // ✅ Must be one of the allowed values\n  },\n});\n```\n\n### Streaming Support\n\n```typescript\n// Type-safe streaming\nconst stream = await db.findWithStream('users', {\n  active: true,\n});\n\nconst reader = stream.getReader();\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n  // value is typed as User\n  console.log(value.name); // ✅ TypeScript knows this is string\n}\n```\n\n### Health Checks\n\n```typescript\nconst health = await db.health();\nconsole.log(health.status); // 'healthy'\n```\n\n## 📚 API Reference\n\n### Client Creation\n\n```typescript\nimport { createClient, GoDBClient } from '@adfharrison1/go-db-typescript-sdk';\n\n// Factory function (recommended)\nconst db = createClient<MySchema>({\n  baseURL: 'http://localhost:8080',\n  timeout: 30000,\n});\n\n// Direct instantiation\nconst db = new GoDBClient<MySchema>({\n  baseURL: 'http://localhost:8080',\n  timeout: 30000,\n});\n```\n\n### Configuration\n\n```typescript\ninterface GoDBClientConfig {\n  baseURL?: string; // Default: 'http://localhost:8080'\n  timeout?: number; // Default: 30000ms\n  headers?: Record<string, string>; // Additional headers\n}\n```\n\n### Available Methods\n\nAll methods are fully type-safe based on your schema:\n\n- `insert<K>(collection: K, doc: Omit<S[K], '_id'>): Promise<S[K]>`\n- `getById<K>(collection: K, id: string): Promise<S[K] | null>`\n- `find<K, Sel>(collection: K, opts?: FindOptions<S[K], Sel>): Promise<Array<Select<S[K], Sel>>>`\n- `updateById<K>(collection: K, id: string, updates: Partial<Omit<S[K], '_id'>>): Promise<S[K]>`\n- `replaceById<K>(collection: K, id: string, doc: Omit<S[K], '_id'>): Promise<S[K]>`\n- `deleteById<K>(collection: K, id: string): Promise<void>`\n- `batchInsert<K>(collection: K, docs: Array<Omit<S[K], '_id'>>): Promise<BatchResponse<S[K]>>`\n- `batchUpdate<K>(collection: K, operations: BatchUpdateOps<S[K]>): Promise<BatchUpdateResponse<S[K]>>`\n- `createIndex<K>(collection: K, field: keyof S[K]): Promise<IndexResponse>`\n- `getIndexes<K>(collection: K): Promise<IndexListResponse>`\n- `findWithStream<K>(collection: K, filters: Partial<S[K]>): Promise<ReadableStream<S[K]>>`\n- `health(): Promise<HealthResponse>`\n\n## 🛠️ Development\n\n### Building\n\n```bash\nyarn build\n```\n\n### Development Mode\n\n```bash\nyarn dev\n```\n\n### Type Checking\n\n```bash\nyarn tsc --noEmit\n```\n\n## 🎯 Why This Approach?\n\n### Traditional Approach (❌)\n\n```typescript\n// No type safety - errors at runtime\nconst user = await client.insert('users', {\n  name: 'John',\n  age: 'thirty', // Oops! Wrong type, but no error until runtime\n  invalidField: 'value', // Oops! Invalid field, but no error until runtime\n});\n\nconst results = await client.find('users', {\n  select: ['name', 'invalid_field'], // Oops! Invalid field, but no error until runtime\n});\n```\n\n### Our Type-Safe Approach (✅)\n\n```typescript\n// Full type safety - errors at compile time\nconst user = await db.insert('users', {\n  name: 'John',\n  age: 30, // ✅ TypeScript enforces correct type\n  // invalidField: 'value', // ❌ TypeScript error at compile time!\n});\n\nconst results = await db.find('users', {\n  select: ['name', 'email'], // ✅ TypeScript validates field names\n});\n```\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please see the main project repository for contribution guidelines.\n\n## 🆘 Support\n\nFor issues and questions, please visit the [GitHub repository](https://github.com/adfharrison1/go-db).\n","readmeFilename":"README.md"}