@objectql/sdk

v1.8.4

Published

21 hours ago

Remote HTTP driver for ObjectQL - Universal client for browser, Node.js, and edge runtimes

Downloads

858

0High
0Medium
0Low

steedos-zhuangjianguo

objectql sdk driver remote http client browser frontend universal api rest fetch typescript esm react vue angular

@objectql/sdk

Remote HTTP Driver for ObjectQL - Universal client for browser, Node.js, and edge runtimes

The @objectql/sdk package provides a type-safe HTTP client for ObjectQL servers. It works seamlessly in browsers, Node.js, Deno, and edge runtimes like Cloudflare Workers.

✨ Features

🌍 Universal Runtime - Works in browsers, Node.js, Deno, and edge environments
📦 Zero Dependencies - Only depends on @objectql/types for type definitions
🔒 Type-Safe - Full TypeScript support with generics
🚀 Modern APIs - Uses native fetch API available in all modern JavaScript runtimes
🎯 RESTful Interface - Clean, predictable API design

📦 Installation

npm install @objectql/sdk @objectql/types

For frontend projects:

# Using npm
npm install @objectql/sdk @objectql/types

# Using yarn
yarn add @objectql/sdk @objectql/types

# Using pnpm
pnpm add @objectql/sdk @objectql/types

🚀 Quick Start

Browser Usage (ES Modules)

<!DOCTYPE html>
<html>
<head>
    <title>ObjectQL SDK Browser Example</title>
</head>
<body>
    <h1>ObjectQL Browser Client</h1>
    <div id="users"></div>

    <script type="module">
        // Option 1: Using unpkg CDN
        import { DataApiClient } from 'https://unpkg.com/@objectql/sdk/dist/index.js';

        // Option 2: Using a bundler (Vite, Webpack, etc.)
        // import { DataApiClient } from '@objectql/sdk';

        const client = new DataApiClient({
            baseUrl: 'http://localhost:3000',
            token: 'your-auth-token' // Optional
        });

        // Fetch and display users
        async function loadUsers() {
            const response = await client.list('users', {
                filter: [['status', '=', 'active']],
                limit: 10
            });

            const usersDiv = document.getElementById('users');
            usersDiv.innerHTML = response.items
                .map(user => `<p>${user.name} - ${user.email}</p>`)
                .join('');
        }

        loadUsers().catch(console.error);
    </script>
</body>
</html>

React / Vue / Angular

import { DataApiClient, MetadataApiClient } from '@objectql/sdk';

// Initialize clients
const dataClient = new DataApiClient({
    baseUrl: process.env.REACT_APP_API_URL || 'http://localhost:3000',
    token: localStorage.getItem('auth_token')
});

const metadataClient = new MetadataApiClient({
    baseUrl: process.env.REACT_APP_API_URL || 'http://localhost:3000'
});

// Use in your components
async function fetchUsers() {
    const response = await dataClient.list('users', {
        filter: [['status', '=', 'active']],
        sort: [['created_at', 'desc']]
    });
    return response.items;
}

Node.js

const { DataApiClient } = require('@objectql/sdk');

const client = new DataApiClient({
    baseUrl: 'http://localhost:3000'
});

async function main() {
    const users = await client.list('users');
    console.log(users.items);
}

main();

📚 API Reference

DataApiClient

Client for CRUD operations on data records.

Constructor

new DataApiClient(config: DataApiClientConfig)

Config Options:

baseUrl (string, required) - Base URL of the ObjectQL server
token (string, optional) - Authentication token
headers (Record<string, string>, optional) - Additional HTTP headers
timeout (number, optional) - Request timeout in milliseconds (default: 30000)

Methods

`list<T>(objectName: string, params?: DataApiListParams): Promise<DataApiListResponse<T>>`

List records with optional filtering, sorting, and pagination.

const users = await client.list('users', {
    filter: [['status', '=', 'active']],
    sort: [['name', 'asc']],
    limit: 20,
    skip: 0,
    fields: ['name', 'email', 'status']
});

`get<T>(objectName: string, id: string | number): Promise<DataApiItemResponse<T>>`

Get a single record by ID.

const user = await client.get('users', 'user_123');

`create<T>(objectName: string, data: DataApiCreateRequest): Promise<DataApiItemResponse<T>>`

Create a new record.

const newUser = await client.create('users', {
    name: 'Alice',
    email: '[email protected]',
    status: 'active'
});

`createMany<T>(objectName: string, data: DataApiCreateManyRequest): Promise<DataApiListResponse<T>>`

Create multiple records at once.

const newUsers = await client.createMany('users', [
    { name: 'Bob', email: '[email protected]' },
    { name: 'Charlie', email: '[email protected]' }
]);

`update<T>(objectName: string, id: string | number, data: DataApiUpdateRequest): Promise<DataApiItemResponse<T>>`

Update an existing record.

const updated = await client.update('users', 'user_123', {
    status: 'inactive'
});

`updateMany(objectName: string, request: DataApiBulkUpdateRequest): Promise<DataApiResponse>`

Update multiple records matching filters.

await client.updateMany('users', {
    filters: [['status', '=', 'pending']],
    data: { status: 'active' }
});

`delete(objectName: string, id: string | number): Promise<DataApiDeleteResponse>`

Delete a record by ID.

await client.delete('users', 'user_123');

`deleteMany(objectName: string, request: DataApiBulkDeleteRequest): Promise<DataApiDeleteResponse>`

Delete multiple records matching filters.

await client.deleteMany('users', {
    filters: [['created_at', '<', '2023-01-01']]
});

`count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse>`

Count records matching filters.

const result = await client.count('users', [['status', '=', 'active']]);
console.log(result.count);

MetadataApiClient

Client for reading object schemas and metadata.

Constructor

new MetadataApiClient(config: MetadataApiClientConfig)

Methods

`listObjects(): Promise<MetadataApiObjectListResponse>`

List all available objects.

const objects = await metadataClient.listObjects();

`getObject(objectName: string): Promise<MetadataApiObjectDetailResponse>`

Get detailed schema for an object.

const userSchema = await metadataClient.getObject('users');
console.log(userSchema.fields);

`getField(objectName: string, fieldName: string): Promise<FieldMetadataResponse>`

Get metadata for a specific field.

const emailField = await metadataClient.getField('users', 'email');

`listActions(objectName: string): Promise<MetadataApiActionsResponse>`

List actions available for an object.

const actions = await metadataClient.listActions('users');

🌐 Browser Compatibility

The SDK uses modern JavaScript APIs available in all current browsers:

fetch API - Available in all modern browsers
Promises/async-await - ES2017+
AbortSignal.timeout() - Chrome 103+, Firefox 100+, Safari 16.4+

Automatic Polyfill

The SDK automatically includes a polyfill for AbortSignal.timeout() that activates when running in older browsers. You don't need to add any polyfills manually - the SDK works universally out of the box!

The polyfill is lightweight and only adds the missing functionality when needed, ensuring compatibility with:

Chrome 90+
Firefox 90+
Safari 15+
Edge 90+

For even older browsers, you may need to add polyfills for:

fetch API (via whatwg-fetch)
AbortController (via abort-controller package)

🔧 Advanced Usage

Custom Headers

const client = new DataApiClient({
    baseUrl: 'http://localhost:3000',
    headers: {
        'X-Custom-Header': 'value',
        'X-Request-ID': crypto.randomUUID()
    }
});

Dynamic Token Updates

class AuthenticatedClient {
    private client: DataApiClient;

    constructor(baseUrl: string) {
        this.client = new DataApiClient({ baseUrl });
    }

    setToken(token: string) {
        this.client = new DataApiClient({
            baseUrl: this.client['baseUrl'],
            token
        });
    }

    async fetchData() {
        return this.client.list('users');
    }
}

Error Handling

import { ObjectQLError, ApiErrorCode } from '@objectql/types';

try {
    await client.create('users', { email: 'invalid' });
} catch (error) {
    if (error instanceof ObjectQLError) {
        console.error('ObjectQL Error:', error.code, error.message);
        
        if (error.code === ApiErrorCode.VALIDATION_ERROR) {
            console.log('Validation failed:', error.details);
        }
    }
}

📖 Examples

React Hook

import { useState, useEffect } from 'react';
import { DataApiClient } from '@objectql/sdk';

const client = new DataApiClient({
    baseUrl: process.env.REACT_APP_API_URL
});

export function useObjectData<T>(objectName: string, params?: any) {
    const [data, setData] = useState<T[]>([]);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState<Error | null>(null);

    useEffect(() => {
        async function fetchData() {
            try {
                setLoading(true);
                const response = await client.list<T>(objectName, params);
                setData(response.items || []);
            } catch (err) {
                setError(err as Error);
            } finally {
                setLoading(false);
            }
        }

        fetchData();
    }, [objectName, JSON.stringify(params)]);

    return { data, loading, error };
}

Vue Composable

import { ref, watchEffect } from 'vue';
import { DataApiClient } from '@objectql/sdk';

const client = new DataApiClient({
    baseUrl: import.meta.env.VITE_API_URL
});

export function useObjectData<T>(objectName: string, params?: any) {
    const data = ref<T[]>([]);
    const loading = ref(true);
    const error = ref<Error | null>(null);

    watchEffect(async () => {
        try {
            loading.value = true;
            const response = await client.list<T>(objectName, params);
            data.value = response.items || [];
        } catch (err) {
            error.value = err as Error;
        } finally {
            loading.value = false;
        }
    });

    return { data, loading, error };
}

🏗️ Architecture

The SDK is designed with the ObjectQL "Trinity" architecture:

@objectql/types (The Contract) - Pure TypeScript interfaces
@objectql/sdk (The Client) - HTTP communication layer
ObjectQL Server (The Backend) - Data processing and storage

┌─────────────────┐
│   Frontend      │
│  (Browser/App)  │
│                 │
│  @objectql/sdk  │
└────────┬────────┘
         │ HTTP/REST
         │
┌────────▼────────┐
│ ObjectQL Server │
│                 │
│  @objectql/core │
└────────┬────────┘
         │
    ┌────┴────┐
    │ SQL/Mongo│
    └─────────┘

📄 License

MIT License - see LICENSE file for details.

🔗 Related Packages

@objectql/types - TypeScript type definitions
@objectql/core - Core ObjectQL engine
@objectql/server - HTTP server implementation

🤝 Contributing

We welcome contributions! Please see the main repository README for guidelines.

📚 Documentation

For complete documentation, visit:

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@objectql/sdk

✨ Features

📦 Installation

🚀 Quick Start

Browser Usage (ES Modules)

React / Vue / Angular

Node.js

📚 API Reference

DataApiClient

Constructor

Methods

list<T>(objectName: string, params?: DataApiListParams): Promise<DataApiListResponse<T>>

get<T>(objectName: string, id: string | number): Promise<DataApiItemResponse<T>>

create<T>(objectName: string, data: DataApiCreateRequest): Promise<DataApiItemResponse<T>>

createMany<T>(objectName: string, data: DataApiCreateManyRequest): Promise<DataApiListResponse<T>>

update<T>(objectName: string, id: string | number, data: DataApiUpdateRequest): Promise<DataApiItemResponse<T>>

updateMany(objectName: string, request: DataApiBulkUpdateRequest): Promise<DataApiResponse>

delete(objectName: string, id: string | number): Promise<DataApiDeleteResponse>

deleteMany(objectName: string, request: DataApiBulkDeleteRequest): Promise<DataApiDeleteResponse>

count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse>

MetadataApiClient

Constructor

Methods

listObjects(): Promise<MetadataApiObjectListResponse>

getObject(objectName: string): Promise<MetadataApiObjectDetailResponse>

getField(objectName: string, fieldName: string): Promise<FieldMetadataResponse>

listActions(objectName: string): Promise<MetadataApiActionsResponse>

🌐 Browser Compatibility

Automatic Polyfill

🔧 Advanced Usage

Custom Headers

Dynamic Token Updates

Error Handling

📖 Examples

React Hook

Vue Composable

🏗️ Architecture

📄 License

🔗 Related Packages

🤝 Contributing

📚 Documentation

`list<T>(objectName: string, params?: DataApiListParams): Promise<DataApiListResponse<T>>`

`get<T>(objectName: string, id: string | number): Promise<DataApiItemResponse<T>>`

`create<T>(objectName: string, data: DataApiCreateRequest): Promise<DataApiItemResponse<T>>`

`createMany<T>(objectName: string, data: DataApiCreateManyRequest): Promise<DataApiListResponse<T>>`

`update<T>(objectName: string, id: string | number, data: DataApiUpdateRequest): Promise<DataApiItemResponse<T>>`

`updateMany(objectName: string, request: DataApiBulkUpdateRequest): Promise<DataApiResponse>`

`delete(objectName: string, id: string | number): Promise<DataApiDeleteResponse>`

`deleteMany(objectName: string, request: DataApiBulkDeleteRequest): Promise<DataApiDeleteResponse>`

`count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse>`

`listObjects(): Promise<MetadataApiObjectListResponse>`

`getObject(objectName: string): Promise<MetadataApiObjectDetailResponse>`

`getField(objectName: string, fieldName: string): Promise<FieldMetadataResponse>`

`listActions(objectName: string): Promise<MetadataApiActionsResponse>`