@goatlab/typesense 0.0.3 → 0.1.0

package/README.md

@@ -53,9 +53,9 @@ const results = await typesense.search.query({
 ## Key Features
 
 - **Grouped API Interface**: Organized methods under logical namespaces (collections, documents, search, admin)
+- **Full Type Safety**: Generic type support for document operations with compile-time checking
 - **Multi-tenancy Support**: Built-in tenant isolation with automatic collection name prefixing
 - **Resilience Features**: Circuit breaker pattern, rate limiting, and automatic retries
-- **Type Safety**: Full TypeScript support with comprehensive type definitions
 - **Schema Management**: Automatic schema caching and version compatibility checks
 - **Stream Support**: Efficient document export with streaming capabilities
 - **Advanced Search**: Support for text search, vector search, and multi-search operations
@@ -101,6 +101,270 @@ const results = await typesense.search.query({
 - **Overrides**: Set up search result overrides
 - **Presets**: Configure search presets
 
+## Type Safety
+
+The TypesenseApi supports full type safety for document operations:
+
+### Basic Typed API
+
+```typescript
+import { createTypedApi } from '@goatlab/typesense'
+
+// Define your document type
+interface Product {
+  id: string
+  title: string
+  price: number
+  inStock: boolean
+}
+
+// Create a typed API instance
+const productApi = createTypedApi<Product>()({
+  prefixUrl: 'http://localhost:8108',
+  token: 'your-api-key',
+  collectionName: 'products'
+})
+
+// All document operations are now type-safe
+await productApi.documents.insert({
+  id: '1',
+  title: 'Widget',
+  price: 99.99,
+  inStock: true
+}) // ✅ Typed
+
+// TypeScript will catch errors at compile time
+// await productApi.documents.insert({ id: '2', title: 'Gadget' })
+// ❌ Error: missing 'price' and 'inStock'
+```
+
+### Direct Generic Usage
+
+```typescript
+const api = new TypesenseApi<Product>({
+  prefixUrl: 'http://localhost:8108',
+  token: 'your-api-key',
+  collectionName: 'products'
+})
+```
+
+## Multi-tenancy
+
+The TypesenseApi provides built-in multi-tenancy support through collection-level isolation:
+
+### Basic Tenant Setup
+
+```typescript
+// Create API instance with tenant ID
+const api = new TypesenseApi({
+  prefixUrl: 'http://localhost:8108',
+  token: 'your-api-key',
+  tenantId: 'acme',  // Tenant ID
+  collectionName: 'products'
+})
+
+// All operations use tenant-prefixed collections automatically
+// Collection name becomes: 'acme__products'
+await api.documents.insert({ id: '1', name: 'Product' })
+```
+
+### Type-Safe Tenant APIs
+
+```typescript
+import { forTenant } from '@goatlab/typesense'
+
+interface Customer {
+  id: string
+  name: string
+  email: string
+}
+
+// Create tenant-specific APIs with compile-time safety
+const tenant1Api = forTenant<Customer, 'tenant1'>('tenant1', {
+  prefixUrl: 'http://localhost:8108',
+  token: 'your-api-key',
+  collectionName: 'customers'
+})
+
+// Tenant ID is preserved in the type
+const tenantId: 'tenant1' = tenant1Api.tenantId // ✅ Type-safe
+```
+
+### Tenant Admin Operations
+
+```typescript
+// List all collections for a tenant
+const collections = await api.listTenantCollections()
+// Returns: ['acme__products', 'acme__users', ...]
+
+// Get base collection names (without prefix)
+const baseNames = await api.listTenantBaseCollectionNames()
+// Returns: ['products', 'users', ...]
+
+// Check if a collection exists
+const exists = await api.tenantCollectionExists('products')
+
+// Delete all tenant collections (use with caution!)
+await api.deleteAllTenantCollections()
+```
+
+### Collection Naming Convention
+
+Tenant collections follow the pattern: `<tenantId>__<baseCollectionName>`
+
+- Tenant IDs are automatically sanitized (lowercase, alphanumeric + hyphens/underscores)
+- Maximum tenant ID length: 128 characters
+- Examples: `acme__products`, `tenant-123__users`
+
+## Schema-based Type Safety
+
+The TypesenseApi provides compile-time type safety for your collections using TypeScript's advanced type system:
+
+### Define Collections with Type Inference
+
+```typescript
+import { TypesenseApi } from '@goatlab/typesense'
+
+// Define your collection schema with proper const assertions
+const ProductCollection = TypesenseApi.defineCollection({
+  name: 'products',
+  fields: [
+    { name: 'id', type: 'string' as const },
+    { name: 'title', type: 'string' as const },
+    { name: 'description', type: 'string' as const, optional: true },
+    { name: 'price', type: 'float' as const },
+    { name: 'inStock', type: 'bool' as const },
+    { name: 'tags', type: 'string[]' as const, optional: true },
+    { name: 'rating', type: 'int32' as const, optional: true }
+  ] as const
+} as const)
+
+// Create a strongly-typed API instance
+const api = TypesenseApi.createSchemaTypedApi(ProductCollection)({
+  prefixUrl: 'http://localhost:8108',
+  token: 'your-api-key'
+})
+
+// All operations are now fully typed with autocomplete
+await api.documents.insert({
+  id: 'prod-001',
+  title: 'Laptop',           // ✅ Required, must be string
+  price: 999.99,            // ✅ Required, must be number
+  inStock: true,            // ✅ Required, must be boolean
+  description: 'Gaming laptop', // ✅ Optional, can be omitted
+  tags: ['gaming', 'laptop']   // ✅ Optional, must be string[]
+})
+
+// TypeScript will catch these errors at compile time:
+// ❌ Missing required field
+// await api.documents.insert({
+//   id: 'prod-002',
+//   price: 99.99,
+//   inStock: true
+//   // Error: Property 'title' is missing
+// })
+
+// ❌ Wrong type
+// await api.documents.insert({
+//   id: 'prod-003',
+//   title: 'Product',
+//   price: '99.99',  // Error: Type 'string' is not assignable to type 'number'
+//   inStock: true
+// })
+```
+
+### One-Step API Creation
+
+For simpler cases, you can define and create the API in one step:
+
+```typescript
+const api = TypesenseApi.createFromSchema({
+  name: 'products',
+  fields: [
+    { name: 'id', type: 'string' as const },
+    { name: 'title', type: 'string' as const },
+    { name: 'price', type: 'float' as const },
+    { name: 'inStock', type: 'bool' as const }
+  ] as const
+} as const)({
+  prefixUrl: 'http://localhost:8108',
+  token: 'your-api-key'
+})
+```
+
+### Complex Field Types
+
+The type inference supports all Typesense field types:
+
+```typescript
+const EventCollection = TypesenseApi.defineCollection({
+  name: 'events',
+  fields: [
+    { name: 'id', type: 'string' as const },
+    { name: 'name', type: 'string' as const },
+    { name: 'timestamp', type: 'int64' as const },
+    { name: 'location', type: 'geopoint' as const },      // [lat, lon] tuple
+    { name: 'attendees', type: 'int32[]' as const, optional: true },
+    { name: 'metadata', type: 'object' as const, optional: true },
+    { name: 'tags', type: 'auto' as const, optional: true }  // string | string[]
+  ] as const
+} as const)
+
+const api = TypesenseApi.createSchemaTypedApi(EventCollection)({
+  prefixUrl: 'http://localhost:8108',
+  token: 'your-api-key'
+})
+
+// Properly typed document
+await api.documents.insert({
+  id: 'evt-001',
+  name: 'Tech Conference',
+  timestamp: Date.now(),
+  location: [37.7749, -122.4194],  // Geopoint as [lat, lon]
+  attendees: [100, 200, 300],      // Optional int32 array
+  metadata: { venue: 'Moscone Center' }  // Optional object
+})
+```
+
+### Key Features
+
+- **Compile-time type checking** - No runtime overhead
+- **Full autocomplete support** - Your IDE knows all field names and types
+- **Optional field handling** - Correctly distinguishes between required and optional fields
+- **All Typesense types supported** - Including arrays, objects, geopoints, and auto fields
+- **Zero runtime validation** - Pure TypeScript type inference
+
+### Alternative Import Methods
+
+The utility functions are also available as direct imports:
+
+```typescript
+import { defineCollection, createSchemaTypedApi } from '@goatlab/typesense'
+
+const collection = defineCollection({...})
+const api = createSchemaTypedApi(collection)({...})
+```
+
+### Type Mapping Reference
+
+| Typesense Type | TypeScript Type |
+|----------------|----------------|
+| `string` | `string` |
+| `string[]` | `string[]` |
+| `int32`, `int64` | `number` |
+| `int32[]`, `int64[]` | `number[]` |
+| `float` | `number` |
+| `float[]` | `number[]` |
+| `bool` | `boolean` |
+| `bool[]` | `boolean[]` |
+| `geopoint` | `[number, number]` |
+| `geopoint[]` | `[number, number][]` |
+| `object` | `Record<string, any>` |
+| `object[]` | `Record<string, any>[]` |
+| `auto` | `string \| string[]` |
+
+**Note**: The `id` field is excluded from the document type for `insert()` operations, as it's handled separately by the TypesenseApi with `WithRequiredId<T>` type.
+
 ## Advanced Configuration
 
 ```typescript

package/dist/TypesenseApi.d.ts

@@ -1,7 +1,10 @@
+import type { TypesenseRateLimitInfo, WithRequiredId, TypesenseDocument, TypesenseCollectionOptions, TypesenseCollection } from './typesense.model';
+import { defineCollection as defineCollectionUtil, type InferFromCollection } from './utils/schema-to-types';
+import { createSchemaTypedApi as createSchemaTypedApiUtil } from './utils/schema-typed-api';
 import { TypesenseHttpClient, type HttpClientOptions } from './components/http-client';
 import { ResiliencePolicy, type ResiliencePolicyOptions } from './components/resilience-policy';
 import { CollectionSchemaManager } from './components/schema-manager';
-interface TypesenseApiOptions extends Omit<HttpClientOptions, 'prefixUrl' | 'token'> {
+export interface TypesenseApiOptions extends Omit<HttpClientOptions, 'prefixUrl' | 'token'> {
     prefixUrl: string;
     token: string;
     tenantId?: string;
@@ -15,6 +18,8 @@ interface TypesenseApiOptions extends Omit<HttpClientOptions, 'prefixUrl' | 'tok
     schemaCacheTtl?: number;
     resilience?: ResiliencePolicyOptions;
     typesenseVersion?: string;
+    onCircuitBreakerStateChange?: (state: 'open' | 'closed' | 'half-open', metadata?: any) => void;
+    onRateLimitUpdate?: (info: TypesenseRateLimitInfo) => void;
 }
 /**
  * Modern, modular Typesense API client with grouped functionality
@@ -40,53 +45,130 @@ interface TypesenseApiOptions extends Omit<HttpClientOptions, 'prefixUrl' | 'tok
  * await api.admin.getMetrics()
  * ```
  */
-export declare class TypesenseApi<T extends Record<string, any> = Record<string, any>> {
+/**
+ * Factory helper for creating typed TypesenseApi instances
+ * @example
+ * ```typescript
+ * interface Product { id: string; title: string; price: number; }
+ * const productApi = createTypedApi<Product>()({
+ *   prefixUrl: 'http://localhost:8108',
+ *   token: 'xyz',
+ *   collectionName: 'products'
+ * })
+ *
+ * // Now all document operations are typed
+ * await productApi.documents.insert({ id: "1", title: "Foo", price: 42 }) // ✅ typed
+ * ```
+ */
+export declare const createTypedApi: <TDoc extends Record<string, any>>() => (options: TypesenseApiOptions) => TypesenseApi<TDoc>;
+/**
+ * Type-safe multitenant API wrapper
+ */
+export type TenantApi<TDoc, TenantId extends string> = TypesenseApi<TDoc> & {
+    readonly tenantId: TenantId;
+};
+export declare class TypesenseApi<TDoc extends Record<string, any> = Record<string, any>> {
     private readonly ctx;
     private withCtx;
     private readonly options;
     readonly httpClient: TypesenseHttpClient;
     readonly resilience: ResiliencePolicy;
     readonly schemaManager: CollectionSchemaManager;
+    /**
+     * Define a strongly-typed collection schema
+     * @example
+     * ```typescript
+     * const ProductCollection = TypesenseApi.defineCollection({
+     *   name: 'products',
+     *   fields: [
+     *     { name: 'id', type: 'string' as const },
+     *     { name: 'title', type: 'string' as const },
+     *     { name: 'price', type: 'float' as const },
+     *     { name: 'inStock', type: 'bool' as const }
+     *   ] as const
+     * } as const)
+     * ```
+     */
+    static defineCollection: typeof defineCollectionUtil;
+    /**
+     * Create a strongly-typed API instance from a collection schema
+     * @example
+     * ```typescript
+     * const ProductCollection = TypesenseApi.defineCollection({...})
+     *
+     * const api = TypesenseApi.createSchemaTypedApi(ProductCollection)({
+     *   prefixUrl: 'http://localhost:8108',
+     *   token: 'xyz'
+     * })
+     *
+     * // Now all document operations are fully typed
+     * await api.documents.insert({
+     *   id: '1',
+     *   title: 'Product',
+     *   price: 99.99,
+     *   inStock: true
+     * })
+     * ```
+     */
+    static createSchemaTypedApi: typeof createSchemaTypedApiUtil;
+    /**
+     * Create a typed API from an inline collection definition (convenience method)
+     * @example
+     * ```typescript
+     * const api = TypesenseApi.createFromSchema({
+     *   name: 'products',
+     *   fields: [
+     *     { name: 'id', type: 'string' as const },
+     *     { name: 'title', type: 'string' as const },
+     *     { name: 'price', type: 'float' as const }
+     *   ] as const
+     * } as const)({
+     *   prefixUrl: 'http://localhost:8108',
+     *   token: 'xyz'
+     * })
+     * ```
+     */
+    static createFromSchema<const C extends TypesenseCollection>(collection: C): (options: Omit<TypesenseApiOptions, "collectionName">) => TypesenseApi<InferFromCollection<C>>;
     constructor(options: TypesenseApiOptions);
     private checkVersion;
     /**
      * Collection management operations
      */
     get collections(): {
-        create: (collection: import("./typesense.model").TypesenseCollection) => any;
+        create: (collection: TypesenseCollection) => any;
         get: (collectionName?: string) => any;
-        update: (collection: Partial<import("./typesense.model").TypesenseCollection>, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
+        update: (collection: Partial<TypesenseCollection>, options?: TypesenseCollectionOptions) => any;
         delete: (collectionName?: string) => any;
         list: () => any;
-        getOrCreate: (collection: import("./typesense.model").TypesenseCollection) => any;
+        getOrCreate: (collection: TypesenseCollection) => any;
     };
     /**
      * Document CRUD operations
      */
     get documents(): {
-        insert: (document: import("./typesense.model").WithRequiredId<Record<string, any>>, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        upsert: (document: import("./typesense.model").WithRequiredId<Record<string, any>>, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        update: (document: Partial<import("./typesense.model").TypesenseDocument<Record<string, any>>> & {
+        insert: (document: WithRequiredId<TDoc>, options?: TypesenseCollectionOptions) => Promise<TypesenseDocument<TDoc>>;
+        upsert: (document: WithRequiredId<TDoc>, options?: TypesenseCollectionOptions) => Promise<TypesenseDocument<TDoc>>;
+        update: (document: Partial<TypesenseDocument<TDoc>> & {
             id: string | number;
-        }, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        delete: (id: string | number, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        getById: (id: string | number, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        import: (documents: string | import("stream").Readable | import("./typesense.model").TypesenseDocument<Record<string, any>>[], format?: import("./typesense.model").TypesenseImportFormat, importOptions?: import("./typesense.model").TypesenseImportOptions, collectionOptions?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        export: (format?: import("./typesense.model").TypesenseExportFormat, options?: import("./typesense.model").TypesenseExportOptions & import("./typesense.model").TypesenseCollectionOptions) => any;
-        exportStream: (options?: import("./typesense.model").TypesenseExportOptions & import("./typesense.model").TypesenseCollectionOptions) => any;
-        deleteByFilter: (filter: string, options?: import("./typesense.model").TypesenseDeleteByFilterOptions & import("./typesense.model").TypesenseCollectionOptions) => any;
-        clear: (options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        search: (query: import("./typesense.model").TypesenseQuery, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        searchText: (query: import("./typesense.model").TypesenseTextQuery, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        searchVector: (query: import("./typesense.model").TypesenseVectorQuery, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
+        }, options?: TypesenseCollectionOptions) => Promise<TypesenseDocument<TDoc>>;
+        delete: (id: string | number, options?: TypesenseCollectionOptions) => any;
+        getById: (id: string | number, options?: TypesenseCollectionOptions) => any;
+        import: (documents: string | import("stream").Readable | TypesenseDocument<Record<string, any>>[], format?: import("./typesense.model").TypesenseImportFormat, importOptions?: import("./typesense.model").TypesenseImportOptions, collectionOptions?: TypesenseCollectionOptions) => any;
+        export: (format?: import("./typesense.model").TypesenseExportFormat, options?: import("./typesense.model").TypesenseExportOptions & TypesenseCollectionOptions) => any;
+        exportStream: (options?: import("./typesense.model").TypesenseExportOptions & TypesenseCollectionOptions) => any;
+        deleteByFilter: (filter: string, options?: import("./typesense.model").TypesenseDeleteByFilterOptions & TypesenseCollectionOptions) => any;
+        clear: (options?: TypesenseCollectionOptions) => any;
+        search: (query: import("./typesense.model").TypesenseQuery, options?: TypesenseCollectionOptions) => any;
+        searchText: (query: import("./typesense.model").TypesenseTextQuery, options?: TypesenseCollectionOptions) => any;
+        searchVector: (query: import("./typesense.model").TypesenseVectorQuery, options?: TypesenseCollectionOptions) => any;
     };
     /**
      * Search operations (alias for documents.search*)
      */
     get search(): {
-        query: (query: import("./typesense.model").TypesenseQuery, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        text: (query: import("./typesense.model").TypesenseTextQuery, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        vector: (query: import("./typesense.model").TypesenseVectorQuery, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
+        query: (query: import("./typesense.model").TypesenseQuery, options?: TypesenseCollectionOptions) => any;
+        text: (query: import("./typesense.model").TypesenseTextQuery, options?: TypesenseCollectionOptions) => any;
+        vector: (query: import("./typesense.model").TypesenseVectorQuery, options?: TypesenseCollectionOptions) => any;
         multi: (request: import("./typesense.model").TypesenseMultiSearchRequest) => any;
     };
     /**
@@ -112,19 +194,19 @@ export declare class TypesenseApi<T extends Record<string, any> = Record<string,
      * Synonym management (v29+)
      */
     get synonyms(): {
-        upsert: (synonym: import("./typesense.model").TypesenseSynonym, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        get: (synonymId: string, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        list: (options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        delete: (synonymId: string, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
+        upsert: (synonym: import("./typesense.model").TypesenseSynonym, options?: TypesenseCollectionOptions) => any;
+        get: (synonymId: string, options?: TypesenseCollectionOptions) => any;
+        list: (options?: TypesenseCollectionOptions) => any;
+        delete: (synonymId: string, options?: TypesenseCollectionOptions) => any;
     };
     /**
      * Search override management (v29+)
      */
     get overrides(): {
-        upsert: (override: import("./typesense.model").TypesenseOverride, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        get: (overrideId: string, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        list: (options?: import("./typesense.model").TypesenseCollectionOptions) => any;
-        delete: (overrideId: string, options?: import("./typesense.model").TypesenseCollectionOptions) => any;
+        upsert: (override: import("./typesense.model").TypesenseOverride, options?: TypesenseCollectionOptions) => any;
+        get: (overrideId: string, options?: TypesenseCollectionOptions) => any;
+        list: (options?: TypesenseCollectionOptions) => any;
+        delete: (overrideId: string, options?: TypesenseCollectionOptions) => any;
     };
     /**
      * Preset management (v29+)
@@ -144,12 +226,12 @@ export declare class TypesenseApi<T extends Record<string, any> = Record<string,
         circuitOpenUntil: number;
         rateLimited: boolean;
         retryAfterUntil: number;
-        rateLimit: import("./typesense.model").TypesenseRateLimitInfo | null;
+        rateLimit: TypesenseRateLimitInfo | null;
     };
     /**
      * Get current rate limit info
      */
-    getRateLimit(): import("./typesense.model").TypesenseRateLimitInfo;
+    getRateLimit(): TypesenseRateLimitInfo;
     /**
      * Get cache statistics
      */
@@ -189,41 +271,3 @@ export declare class TypesenseApi<T extends Record<string, any> = Record<string,
      */
     destroy(): void;
 }
-export * from './actions/collections/createCollection';
-export * from './actions/collections/getCollection';
-export * from './actions/collections/updateCollection';
-export * from './actions/collections/deleteCollection';
-export * from './actions/collections/listCollections';
-export * from './actions/collections/getOrCreateCollection';
-export * from './actions/documents/insertDocument';
-export * from './actions/documents/upsertDocument';
-export * from './actions/documents/updateDocument';
-export * from './actions/documents/deleteDocument';
-export * from './actions/documents/getDocumentById';
-export * from './actions/documents/importDocuments';
-export * from './actions/documents/exportDocuments';
-export * from './actions/documents/deleteByFilter';
-export * from './actions/documents/clearCollection';
-export * from './actions/search/search';
-export * from './actions/search/multiSearch';
-export * from './actions/admin/health';
-export * from './actions/admin/metrics';
-export * from './actions/admin/getCollectionStats';
-export * from './actions/aliases/createOrUpdateAlias';
-export * from './actions/aliases/getAlias';
-export * from './actions/aliases/listAliases';
-export * from './actions/aliases/deleteAlias';
-export * from './actions/synonyms/upsertSynonym';
-export * from './actions/synonyms/getSynonym';
-export * from './actions/synonyms/listSynonyms';
-export * from './actions/synonyms/deleteSynonym';
-export * from './actions/overrides/upsertOverride';
-export * from './actions/overrides/getOverride';
-export * from './actions/overrides/listOverrides';
-export * from './actions/overrides/deleteOverride';
-export * from './actions/presets/upsertPreset';
-export * from './actions/presets/getPreset';
-export * from './actions/presets/listPresets';
-export * from './actions/presets/deletePreset';
-export * from './utils/tenant';
-export type { TypesenseCollectionOutput } from './typesense.model';