@tinycloud/sdk-services 2.0.1 → 2.0.2-beta.0

package/dist/kv/IKVService.d.ts

@@ -1,148 +0,0 @@
-/**
- * IKVService - Interface for KV (Key-Value) service.
- *
- * Platform-agnostic interface for key-value storage operations.
- * Implementations use dependency injection via IServiceContext.
- */
-import { IService, Result } from "../types";
-import type { IPrefixedKVService } from "./PrefixedKVService";
-import { KVServiceConfig, KVGetOptions, KVPutOptions, KVListOptions, KVDeleteOptions, KVHeadOptions, KVResponse, KVListResponse } from "./types";
-/**
- * KV service interface.
- *
- * Provides key-value storage operations with:
- * - Result type pattern (no throwing)
- * - Optional prefix namespacing
- * - Configurable timeouts
- * - Abort signal support
- *
- * @example
- * ```typescript
- * const result = await kv.get('user/settings');
- * if (result.ok) {
- *   console.log('Settings:', result.data.data);
- * } else {
- *   console.error('Error:', result.error.code);
- * }
- * ```
- */
-export interface IKVService extends IService {
-    /**
-     * Get a value by key.
-     *
-     * @param key - The key to retrieve
-     * @param options - Optional get configuration
-     * @returns Result with the stored value and headers
-     *
-     * @example
-     * ```typescript
-     * const result = await kv.get<UserSettings>('settings');
-     * if (result.ok) {
-     *   const settings = result.data.data;
-     *   const etag = result.data.headers.etag;
-     * }
-     * ```
-     */
-    get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
-    /**
-     * Store a value at a key.
-     *
-     * Objects are automatically JSON stringified.
-     * Strings are stored as-is.
-     *
-     * @param key - The key to store under
-     * @param value - The value to store
-     * @param options - Optional put configuration
-     * @returns Result indicating success/failure
-     *
-     * @example
-     * ```typescript
-     * // Store an object (auto-stringified)
-     * const result = await kv.put('settings', { theme: 'dark' });
-     *
-     * // Store a string
-     * const result = await kv.put('name', 'Alice');
-     * ```
-     */
-    put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
-    /**
-     * List keys with optional prefix filtering.
-     *
-     * @param options - Optional list configuration
-     * @returns Result with array of matching keys
-     *
-     * @example
-     * ```typescript
-     * // List all keys
-     * const result = await kv.list();
-     *
-     * // List keys with a specific prefix
-     * const result = await kv.list({ prefix: 'users/' });
-     * ```
-     */
-    list(options?: KVListOptions): Promise<Result<KVListResponse>>;
-    /**
-     * Delete a key.
-     *
-     * @param key - The key to delete
-     * @param options - Optional delete configuration
-     * @returns Result indicating success/failure
-     *
-     * @example
-     * ```typescript
-     * const result = await kv.delete('old-key');
-     * if (!result.ok && result.error.code === 'KV_NOT_FOUND') {
-     *   console.log('Key already deleted');
-     * }
-     * ```
-     */
-    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
-    /**
-     * Get metadata for a key without retrieving the value.
-     *
-     * Useful for checking if a key exists or getting headers
-     * without downloading the full value.
-     *
-     * @param key - The key to check
-     * @param options - Optional head configuration
-     * @returns Result with headers only
-     *
-     * @example
-     * ```typescript
-     * const result = await kv.head('large-file');
-     * if (result.ok) {
-     *   console.log('Size:', result.data.headers.contentLength);
-     * }
-     * ```
-     */
-    head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
-    /**
-     * Create a prefix-scoped view of this KV service.
-     *
-     * Returns a PrefixedKVService that automatically prefixes all
-     * key operations with the specified prefix. This enables apps
-     * to isolate their data within a shared space.
-     *
-     * @param prefix - The prefix to apply to all operations
-     * @returns A PrefixedKVService scoped to the prefix
-     *
-     * @example
-     * ```typescript
-     * const myApp = kv.withPrefix('/app.myapp.com');
-     *
-     * // Operations are automatically prefixed
-     * await myApp.put('settings.json', { theme: 'dark' });
-     * // -> Actually writes to: /app.myapp.com/settings.json
-     *
-     * // Nested prefixes
-     * const settings = myApp.withPrefix('/settings');
-     * await settings.get('theme.json');  // -> /app.myapp.com/settings/theme.json
-     * ```
-     */
-    withPrefix(prefix: string): IPrefixedKVService;
-    /**
-     * Service configuration.
-     */
-    readonly config: KVServiceConfig;
-}
-//# sourceMappingURL=IKVService.d.ts.map

package/dist/kv/IKVService.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"IKVService.d.ts","sourceRoot":"","sources":["../../src/kv/IKVService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,eAAe,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,UAAW,SAAQ,QAAQ;IAC1C;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAErC;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;IAE/D;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAEtE;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAE9E;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC"}

package/dist/kv/IKVService.js

@@ -1,8 +0,0 @@
-/**
- * IKVService - Interface for KV (Key-Value) service.
- *
- * Platform-agnostic interface for key-value storage operations.
- * Implementations use dependency injection via IServiceContext.
- */
-export {};
-//# sourceMappingURL=IKVService.js.map

package/dist/kv/IKVService.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IKVService.js","sourceRoot":"","sources":["../../src/kv/IKVService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/kv/KVService.d.ts

@@ -1,155 +0,0 @@
-/**
- * KVService - Key-Value storage service implementation.
- *
- * Platform-agnostic KV service that works with both web-sdk and node-sdk.
- * Uses dependency injection via IServiceContext for platform dependencies.
- */
-import { BaseService } from "../base/BaseService";
-import { Result } from "../types";
-import { IKVService } from "./IKVService";
-import { IPrefixedKVService } from "./PrefixedKVService";
-import { KVServiceConfig, KVGetOptions, KVPutOptions, KVListOptions, KVDeleteOptions, KVHeadOptions, KVResponse, KVListResponse } from "./types";
-/**
- * KV service implementation.
- *
- * Provides key-value storage operations using TinyCloud's KV API.
- * Uses the Result type pattern for explicit error handling.
- *
- * @example
- * ```typescript
- * // Register with SDK
- * const sdk = new TinyCloud({
- *   services: { kv: KVService },
- *   serviceConfigs: { kv: { prefix: 'myapp' } },
- * });
- *
- * // Use the service
- * const result = await sdk.kv.get('settings');
- * if (result.ok) {
- *   console.log(result.data.data);
- * }
- * ```
- */
-export declare class KVService extends BaseService implements IKVService {
-    /**
-     * Service identifier for registration.
-     */
-    static readonly serviceName = "kv";
-    /**
-     * Service configuration.
-     */
-    protected _config: KVServiceConfig;
-    /**
-     * Create a new KVService instance.
-     *
-     * @param config - Service configuration
-     */
-    constructor(config?: KVServiceConfig);
-    /**
-     * Get the service configuration.
-     */
-    get config(): KVServiceConfig;
-    private parseQuotaInfo;
-    private handleQuotaErrorResponse;
-    /**
-     * Get the full path with optional prefix.
-     *
-     * @param key - The key
-     * @param prefixOverride - Optional prefix override
-     * @returns The full path
-     */
-    private getFullPath;
-    /**
-     * Get the host URL.
-     */
-    private get host();
-    /**
-     * Execute an invoke operation.
-     *
-     * @param path - Resource path
-     * @param action - KV action
-     * @param body - Optional request body
-     * @param signal - Optional abort signal
-     * @returns Fetch response
-     */
-    private invokeOperation;
-    /**
-     * Create KVResponseHeaders from fetch response headers.
-     *
-     * @param headers - Fetch response headers
-     * @returns KVResponseHeaders object
-     */
-    private createResponseHeaders;
-    /**
-     * Parse response body based on content type.
-     *
-     * @param response - Fetch response
-     * @param raw - Whether to return raw text
-     * @returns Parsed data
-     */
-    private parseResponse;
-    /**
-     * Get a value by key.
-     */
-    get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
-    /**
-     * Store a value at a key.
-     */
-    put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
-    /**
-     * List keys with optional prefix filtering.
-     */
-    list(options?: KVListOptions): Promise<Result<KVListResponse>>;
-    /**
-     * Delete a key.
-     */
-    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
-    /**
-     * Get metadata for a key without retrieving the value.
-     */
-    head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
-    /**
-     * Create a prefix-scoped view of this KV service.
-     *
-     * Returns a PrefixedKVService that automatically prefixes all
-     * key operations with the specified prefix. This enables apps
-     * to isolate their data within a shared space.
-     *
-     * @param prefix - The prefix to apply to all operations
-     * @returns A PrefixedKVService scoped to the prefix
-     *
-     * ## Prefix Conventions
-     *
-     * | Pattern | Use Case | Example |
-     * | -- | -- | -- |
-     * | `/app.{domain}/` | App-private data | `/app.photos.xyz/settings.json` |
-     * | `/{type}/` | Shared data type | `/photos/vacation.jpg` |
-     * | `/.{name}/` | Hidden/system data | `/.cache/thumbnails/` |
-     * | `/public/` | Explicitly shareable | `/public/profile.json` |
-     *
-     * @example
-     * ```typescript
-     * const space = sdk.space('default');
-     *
-     * // Create prefix-scoped views
-     * const myApp = space.kv.withPrefix('/app.myapp.com');
-     * const sharedPhotos = space.kv.withPrefix('/photos');
-     *
-     * // Operations are automatically prefixed
-     * await myApp.put('settings.json', { theme: 'dark' });
-     * // -> Actually writes to: /app.myapp.com/settings.json
-     *
-     * await myApp.get('settings.json');
-     * // -> Actually reads from: /app.myapp.com/settings.json
-     *
-     * await sharedPhotos.list();
-     * // -> Lists: /photos/*
-     *
-     * // Nested prefixes
-     * const settings = myApp.withPrefix('/settings');
-     * await settings.get('theme.json');  // -> /app.myapp.com/settings/theme.json
-     * ```
-     */
-    withPrefix(prefix: string): IPrefixedKVService;
-}
-//# sourceMappingURL=KVService.d.ts.map

package/dist/kv/KVService.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"KVService.d.ts","sourceRoot":"","sources":["../../src/kv/KVService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EACL,MAAM,EAMP,MAAM,UAAU,CAAC;AASlB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAqB,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,eAAe,EACf,aAAa,EACb,UAAU,EACV,cAAc,EAGf,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAU,SAAQ,WAAY,YAAW,UAAU;IAC9D;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAW,QAAQ;IAEnC;;OAEG;IACH,UAAkB,OAAO,EAAE,eAAe,CAAC;IAE3C;;;;OAIG;gBACS,MAAM,GAAE,eAAoB;IAKxC;;OAEG;IACH,IAAI,MAAM,IAAI,eAAe,CAE5B;IAGD,OAAO,CAAC,cAAc;IAetB,OAAO,CAAC,wBAAwB;IAwChC;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,KAAK,IAAI,GAEf;IAED;;;;;;;;OAQG;YACW,eAAe;IAsB7B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;;;;OAMG;YACW,aAAa;IA+B3B;;OAEG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IA2DjC;;OAEG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IAmEpC;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAgEpE;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAuD3E;;OAEG;IACG,IAAI,CACR,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IA0DpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB;CAG/C"}