@asaidimu/hestia 1.0.1 → 1.0.2

package/core/pager.ts

@@ -1,162 +0,0 @@
-import type { QueryDSL, QueryFilter, SortConfiguration } from "@asaidimu/query";
-import { DELETE_SYMBOL, type DataStore } from "@asaidimu/utils-store";
-import type { Page, PagedData, PagerRefreshOptions } from "./types";
-export type { PagerRefreshOptions }
-import { Debouncer } from "@asaidimu/utils-sync";
-
-declare function requestIdleCallback(cb: (deadline: { didTimeout: boolean }) => void): void;
-
-export interface PageOptions<T extends Record<string, any>> {
-  page?: number;
-  size?: number;
-  sort?: SortConfiguration<T> | SortConfiguration<T>[];
-  filter?: QueryFilter<T>;
-}
-
-const sentinel = {
-  data: [],
-  loading: true,
-  page: {
-    number: 1,
-    size: 20,
-    count: 0,
-    total: 0,
-    pages: 1,
-  },
-};
-export function createPagedController<T extends Record<string, any>>(
-  collectionName: string,
-  store: DataStore<any>,
-  options: PageOptions<T>,
-  find: (query: QueryDSL<T>) => Promise<Page<T>>,
-): PagedData<T> {
-  let currentPage = options.page ?? 1;
-  let currentSize = options.size ?? 20;
-  let currentSort = options.sort;
-  let currentFilter = options.filter;
-  const debounce = new Debouncer({ delay: 50 });
-
-  const CACHE_KEY = `${collectionName}_pager_state_`;
-  store.set({
-    [CACHE_KEY]: {
-      data: [],
-      loading: false,
-      error: DELETE_SYMBOL,
-      page: { number: 1, size: 20, count: 0, total: 0, pages: 1 },
-    },
-  });
-
-  const buildQuery = (opts?: PagerRefreshOptions): QueryDSL<T> => {
-    const page = opts?.page ?? currentPage;
-    const size = opts?.size ?? currentSize;
-    const query: QueryDSL<T> = {
-      pagination: {
-        type: "offset",
-        offset: (page - 1) * size,
-        limit: size,
-      },
-    };
-    const sort = opts?.sort ?? currentSort;
-    if (sort) {
-      query.sort = Array.isArray(sort) ? sort : [sort];
-    }
-    const filter = opts?.filter ?? currentFilter;
-    if (filter) {
-      query.filters = filter;
-    }
-    return query;
-  };
-
-  const load = async (opts?: PagerRefreshOptions) => {
-    await store.set({
-      [CACHE_KEY]: {
-        loading: true,
-        error: DELETE_SYMBOL,
-      },
-    });
-
-    return await new Promise((resolve) => {
-      resolve(
-        debounce.do(async () => {
-          requestIdleCallback(() => {
-            requestIdleCallback(async () => {
-              try {
-                const result = await find(buildQuery(opts));
-                await store.set({ [CACHE_KEY]: result });
-              } catch (error) {
-                await store.set({
-                  [CACHE_KEY]: {
-                    ...sentinel,
-                    error,
-                  },
-                });
-              } finally {
-                await store.set({
-                  [CACHE_KEY]: {
-                    loading: false,
-                  },
-                });
-              }
-            });
-          });
-        }),
-      );
-    });
-  };
-
-  const selector = store.select((s: any) => s[CACHE_KEY]);
-  // TODO: Investigate bug. If by any chance a selectors subscription reaches
-  // zero, it is auto discarded. This might be a problem if we are holding it
-  // fix this
-  const unsub = selector.subscribe(() => {});
-
-  const controller: PagedData<T> = {
-    page: () => selector.get() ?? sentinel,
-
-    navigate: async (page: number) => {
-      if (page < 1) throw new Error("Page number must be >= 1");
-      currentPage = page;
-      await load({
-        page,
-      });
-    },
-
-    resize: async (size: number, page: number) => {
-      if (size < 1) throw new Error("Page size must be >= 1");
-      currentSize = size;
-      currentPage = page;
-      await load();
-    },
-
-    sort: async (sort) => {
-      currentSort = Array.isArray(sort) ? sort : [sort];
-      currentPage = 1;
-      await load();
-    },
-
-    filter: async (filter) => {
-      currentFilter = filter;
-      currentPage = 1;
-      await load();
-    },
-
-    refresh: async (opts) => {
-      await Promise.all([
-        new Promise((resolve) => setTimeout(resolve, opts?.delay || 0)),
-        load(opts),
-      ]);
-    },
-
-    subscribe: (listener) => {
-      return selector.subscribe(listener);
-    },
-
-    invalidate: async () => {
-      await store.set({ [CACHE_KEY]: DELETE_SYMBOL });
-      unsub();
-    },
-
-    id: () => CACHE_KEY,
-  };
-  return controller;
-}

package/core/types.ts

@@ -1,279 +0,0 @@
-import type { QueryFilter, SortConfiguration } from "@asaidimu/query";
-
-// Internal metadata managed by Anansi
-interface DocumentMetadata {
-  checksum: string; // Integrity hash of the document
-  created: string; // Timestamp (often as a numeric string / nanoseconds)
-  updated: string; // Timestamp (often as a numeric string / nanoseconds)
-  version: number; // Optimistic locking version (increments on each write)
-}
-
-// The base envelope applied to every single document in the system
-interface BaseDocument {
-  _id_: string;
-  _metadata_: DocumentMetadata;
-}
-
-// Generic Document type: base envelope + your custom properties T
-export type Document<T extends Record<string, any>> = BaseDocument & T;
-
-/**
- * Provides comprehensive pagination information for a collection of records.
- */
-export type PaginationInfo = {
-  /** The current page number (1-based). */
-  number: number;
-
-  /** The maximum number of items requested per page. */
-  size: number;
-
-  /** The number of items in the current page */
-  count: number;
-
-  /** The total count of all items across all pages. */
-  total: number;
-
-  /** The total number of available pages. */
-  pages: number;
-};
-
-/**
- * Represents a single paginated response containing a list of records and pagination details.
- * @template T The type of the records in the page.
- */
-export interface Page<T extends Record<string, any>> {
-  /** The array of records for the current page. */
-  data: Document<T>[];
-
-  /** Indicates if the data query is currently loading. */
-  loading: boolean;
-
-  /** An error object if the query failed, otherwise `undefined`. */
-  error?: any | undefined;
-
-  /** Pagination metadata providing details about the current page and total collection. */
-  page: PaginationInfo;
-}
-
-export interface PagerRefreshOptions {
-  sort?: SortConfiguration | SortConfiguration[];
-  filter?: QueryFilter;
-  delay?: number;
-  size?: number;
-  page?: number;
-}
-/**
- * Represents the complete state and control mechanisms for consuming paginated data.
- * @template T The type of the records in the page (`TableRowData` or an extension).
- */
-export interface PagedData<T extends Record<string, any>> {
-  id: () => string
-
-  /** The current paginated data, or `undefined` if not found or still loading. */
-  page: () => Page<T>;
-
-  /** Function to fetch a specific page of data.
-   * @param page The 1-based page number to fetch.
-   */
-  navigate: (page: number) => Promise<void>;
-
-  sort: (sort: SortConfiguration<T> | SortConfiguration<T>[]) => Promise<void>;
-  filter: (filter?: QueryFilter<T>) => Promise<void>;
-
-  /**
-   * Function to change the page size of the data
-   */
-  resize: (size: number, page: number) => Promise<void>;
-
-  /**
-   * Function to force a refresh of the current page data, optionally with a delay.
-   * @param delay Optional delay in milliseconds before the refresh operation starts.
-   */
-  refresh: (opts?: PagerRefreshOptions) => Promise<void>;
-
-  /**
-   * Subscribes to page changes.
-   * The callback is invoked immediately with the current page, and then on every
-   * subsequent change (navigation, resize, SSE patch, refresh).
-   *
-   * @param listener A function that receives the current Page<T>.
-   * @returns An unsubscribe function.
-   */
-  subscribe: (listener: (page: Page<T>) => void) => () => void;
-
-  /**
-   * Invalidates the pagination controller, cleaning up any cached resources
-   * (e.g., store subscriptions, in‑flight requests) and removing internal state.
-   * After calling `invalidate()`, the controller should no longer be used.
-   *
-   * This is useful when the component using the pager is unmounted or when
-   * you need to reset the pagination state completely.
-   */
-  invalidate: () => void;
-}
-
-/**
- * Represents an event emitted by the store, typically for notifications or state changes.
- */
-export interface StoreEvent {
-  /** The scope of the event, indicating its type and context. Custom scopes are allowed. */
-  scope: string;
-  /** Optional payload carrying data related to the event. */
-  payload?: any;
-}
-
-/**
- * Defines the core interface for interacting with a remote data store.
- * @template T The type of the records managed by the store, extending Record.
- * @template TFindOptions Options for the find operation.
- * @template TReadOptions Options for the read operation.
- * @template TListOptions Options for the list operation.
- * @template TPageOptions Options for the paging operation.
- * @template TDeleteOptions Options for the delete operation.
- * @template TUpdateOptions Options for the update operation.
- * @template TCreateOptions Options for the create operation.
- * @template TUploadOptions Options for the upload operation.
- * @template TStreamOptions Options for the stream operation.
- */
-export interface DocumentStore<
-  T extends Record<string, any>,
-  TFindOptions = Record<string, unknown>,
-  TReadOptions = Record<string, unknown>,
-  TListOptions = Record<string, unknown>,
-  TPageOptions = Record<string, unknown>,
-  TDeleteOptions = Record<string, unknown>,
-  TUpdateOptions = Record<string, unknown>,
-  TCreateOptions = Record<string, unknown>,
-  TUploadOptions = Record<string, unknown>,
-  TStreamOptions = Record<string, unknown>,
-> {
-  /**
-   * Finds records based on provided options, returning a paginated result.
-   * @param options The options for the find operation.
-   * @returns A promise that resolves to a Page of records.
-   */
-  find: (options: TFindOptions) => Promise<Page<T>>;
-
-  /**
-   * Reads a single record by its identifier or other read options.
-   * @param options The options for the read operation, typically including an ID.
-   * @returns A promise that resolves to the record or undefined if not found.
-   */
-  read: (options: TReadOptions) => Promise<Document<T> | undefined>;
-
-  /**
-   * Lists records based on provided options, returning a paginated result.
-   * @param options The options for the list operation.
-   * @returns A promise that resolves to a Page of records.
-   */
-  list: (options: TListOptions) => Promise<Page<T>>;
-
-  /**
-   * Deletes a record based on provided options, typically including an ID.
-   * @param options The options for the delete operation.
-   * @returns A promise that resolves when the deletion is complete.
-   */
-  delete: (options: TDeleteOptions) => Promise<void>;
-
-  /**
-   * Updates an existing record.
-   * @param props An object containing the ID of the record to update, the partial data, and optional update options.
-   * @returns A promise that resolves to the updated record or undefined if not found.
-   */
-  update: (props: {
-    data: Partial<T>;
-    options?: TUpdateOptions;
-  }) => Promise<Document<T> | undefined>;
-
-  /**
-   * Creates a new record.
-   * @param props An object containing the data for the new record and optional create options.
-   * @returns A promise that resolves to the newly created record or undefined if creation failed.
-   */
-  create: (props: {
-    data: Partial<T>;
-    options?: TCreateOptions;
-  }) => Promise<Document<T> | undefined>;
-
-  /**
-   * Uploads a file associated with a record. Optionally updates the record with upload details.
-   * @param props An object containing the file to upload and optional upload options.
-   * @returns A promise that resolves to the updated record after upload or undefined if upload failed.
-   */
-  upload: (props: {
-    file: File;
-    options?: TUploadOptions;
-  }) => Promise<Document<T> | undefined>;
-
-  /**
-   * Subscribes to store events for a given scope.
-   * @param scope The event scope to subscribe to (e.g., 'todos:created:success', '*').
-   * @param callback The function to call when an event matching the scope is received.
-   * @returns A promise that resolves to an unsubscribe function. Call this function to stop receiving events.
-   */
-  subscribe(
-    scope: string,
-    callback: (event: StoreEvent) => void,
-  ): Promise<() => void>;
-  /**
-   * Notifies the store of an event, which can then be broadcast to subscribers.
-   * @param event The StoreEvent to notify.
-   * @returns A promise that resolves when the notification has been processed.
-   */
-  notify: (event: StoreEvent) => Promise<void>;
-
-  /**
-   * Establishes a stream of records based on provided options.
-   * @param options Options for configuring the stream (e.g., batch size, delay, filters).
-   * @param onStreamChange A callback function that is called when the stream's status changes.
-   * @returns An object containing the async iterable stream, a cancel function, and a status getter.
-   */
-  stream: (
-    options: TStreamOptions,
-    onStreamChange: () => void,
-  ) => {
-    /** An async iterable that yields records as they become available in the stream. */
-    stream: () => AsyncIterable<Document<T>>;
-    /** A function to call to cancel the ongoing stream. */
-    cancel: () => void;
-    /** A getter function that returns the current status of the stream ('active', 'cancelled', or 'completed'). */
-    status: () => "active" | "cancelled" | "completed";
-  };
-
-  /**
-   * Creates a paginated data controller for this store.
-   *
-   * @param options - The pagination options, whose type is defined by the
-   *                  store's `TPageOptions` generic parameter. This lets you
-   *                  pass any configuration (e.g., filters, sorting, custom
-   *                  pagination metadata) that your store implementation needs.
-   * @returns A `PagedData<T>` controller that manages loading, navigation,
-   *          resizing, and refresh.
-   *
-   * @example
-   * // Define your store with a custom TPageOptions type
-   * interface MyTodoStore extends DocumentStore<
-   *   Todo,
-   *   FindOptions,
-   *   ReadOptions,
-   *   ListOptions,
-   *   { page: number; size: number; sort?: string; filter?: string }
-   * > {}
-   *
-   * // Use it
-   * const todosPaged = myTodoStore.page({
-   *   page: 1,
-   *   size: 10,
-   *   sort: 'createdAt',
-   *   filter: 'done:false'
-   * });
-   *
-   * // Get current page state
-   * const { data, loading, page } = todosPaged.page();
-   * console.log(`Page ${page.number} of ${page.pages}`);
-   *
-   * // Navigate
-   * await todosPaged.navigate(2);
-   */
-  page(options: TPageOptions): PagedData<T>;
-}

package/index.ts

@@ -1,39 +0,0 @@
-// Core
-export * from "./core/client"
-export { HestiaCollection } from "./core/collection"
-export * from "./core/errors"
-export * from "./core/types"
-export { createPagedController } from "./core/pager"
-
-// Auth
-export * from "./auth/store"
-export * from "./auth/types"
-
-// System: identity
-export * from "./system/identity/store"
-export * from "./system/identity/types"
-
-// System: api-keys
-export * from "./system/api-keys/store"
-export * from "./system/api-keys/types"
-
-// System: policies
-export * from "./system/policies/store"
-export * from "./system/policies/types"
-
-// System: logs
-export * from "./system/logs/store"
-export * from "./system/logs/types"
-
-// Blobs
-export * from "./blobs/store"
-export * from "./blobs/types"
-
-// Collections
-export * from "./collections/store"
-export * from "./collections/types"
-
-// Container
-export { HestiaClient } from "./container"
-
-export * from "./utils"

package/system/api-keys/store.ts

@@ -1,107 +0,0 @@
-import type { QueryDSL } from "@asaidimu/query"
-import { HestiaNetworkClient } from "../../core/client"
-import { ReactiveDataStore } from "@asaidimu/utils-store"
-import { createPagedController } from "../../core/pager"
-import type { Document, Page, PagedData, StoreEvent } from "../../core/types"
-import type { DocumentStore } from "../../core/types"
-import type { APIKey, APIKeyWithSecret, CreateKeyRequest, UpdateKeyRequest } from "./types"
-
-export class HestiaKeyStore implements DocumentStore<APIKey, QueryDSL<APIKey>, string, QueryDSL<APIKey>, Record<string, unknown>, string, string, Record<string, unknown>> {
-  private pager: PagedData<APIKey>
-
-  constructor(private client: HestiaNetworkClient) {
-    this.pager = createPagedController<APIKey>(
-      "_api_key_",
-      new ReactiveDataStore<any>({}),
-      {},
-      (query) => this.find(query),
-    )
-  }
-
-  private basePath = "/system/apikeys/key"
-
-  async find(_query?: QueryDSL<APIKey>): Promise<Page<APIKey>> {
-    const res = await this.client.get<{
-      data: Document<APIKey>[];
-      metadata?: { page?: any };
-    }>(this.basePath)
-    const items = res.data?.data ?? []
-    const pageMeta = res.data?.metadata?.page ?? {
-      number: 1,
-      size: items.length,
-      count: items.length,
-      total: items.length,
-      pages: 1,
-    }
-    return { data: items, loading: false, page: pageMeta }
-  }
-
-  async list(options?: QueryDSL<APIKey>): Promise<Page<APIKey>> {
-    return options ? this.find(options) : this.find()
-  }
-
-  async read(id: string): Promise<Document<APIKey> | undefined> {
-    try {
-      const res = await this.client.get<{ data: Document<APIKey> }>(
-        `${this.basePath}/${encodeURIComponent(id)}`,
-      )
-      return res.data?.data
-    } catch (err: any) {
-      if (err?.code === "SYNC-001-NF") return undefined
-      if (err?.code === "INTERNAL_ERROR" && typeof err?.message === "string" && err.message.includes("not found")) return undefined
-      throw err
-    }
-  }
-
-  async create(props: { data: Partial<APIKey> }): Promise<Document<APIKey> | undefined> {
-    const res = await this.client.post<{ data: Document<APIKeyWithSecret> }>(
-      this.basePath,
-      props.data as CreateKeyRequest,
-    )
-    return res.data!.data
-  }
-
-  async update(props: { data: Partial<APIKey>; options?: string }): Promise<Document<APIKey> | undefined> {
-    const id = props.options!
-    const res = await this.client.patch<{ data: Document<APIKey> }>(
-      `${this.basePath}/${encodeURIComponent(id)}`,
-      props.data as UpdateKeyRequest,
-    )
-    return res.data!.data
-  }
-
-  async delete(id: string): Promise<void> {
-    await this.client.delete(`${this.basePath}/${encodeURIComponent(id)}`)
-  }
-
-  async upload(_props: { file: File }): Promise<Document<APIKey> | undefined> {
-    throw new Error("Upload not supported for API keys")
-  }
-
-  async subscribe(_scope: string, _callback: (event: StoreEvent) => void): Promise<() => void> {
-    throw new Error("Subscription not supported for API keys")
-  }
-
-  async notify(_event: StoreEvent): Promise<void> {
-    throw new Error("Notify not supported for API keys")
-  }
-
-  stream(_options: Record<string, unknown>, _onStreamChange: () => void): {
-    stream: () => AsyncIterable<Document<APIKey>>;
-    cancel: () => void;
-    status: () => "active" | "cancelled" | "completed";
-  } {
-    throw new Error("Stream not supported for API keys")
-  }
-
-  page(_options?: Record<string, unknown>): PagedData<APIKey> {
-    return this.pager
-  }
-
-  async rotate(id: string): Promise<Document<APIKeyWithSecret>> {
-    const res = await this.client.post<{ data: Document<APIKeyWithSecret> }>(
-      `${this.basePath}/${encodeURIComponent(id)}`,
-    )
-    return res.data!.data
-  }
-}

package/system/api-keys/types.ts

@@ -1,31 +0,0 @@
-export interface APIKey {
-  _id_: string
-  name: string
-  prefix: string
-  operations: string[]
-  status: string
-  expiry?: string | null
-  environment?: string
-  usage?: number
-  last_used?: string | null
-  _metadata_: Record<string, unknown>
-}
-
-export interface APIKeyWithSecret extends APIKey {
-  key: string
-}
-
-export interface CreateKeyRequest {
-  name: string
-  environment?: string
-  operations?: string[]
-  expiry?: string
-}
-
-export interface UpdateKeyRequest {
-  name?: string
-  environment?: string
-  operations?: string[]
-  status?: "active" | "revoked"
-  expiry?: string
-}

package/system/capabilities/store.ts

@@ -1,67 +0,0 @@
-import { HestiaNetworkClient } from "../../core/client";
-import type { Document, Page, PagedData, StoreEvent } from "../../core/types";
-import type { DocumentStore } from "../../core/types";
-
-export class HestiaCapabilities implements DocumentStore<any, Record<string, unknown>, string, Record<string, unknown>, Record<string, unknown>, string, string, Record<string, unknown>> {
-  constructor(
-    private client: HestiaNetworkClient,
-  ) {
-
-  }
-
-  async find(_query?: Record<string, unknown>): Promise<Page<any>> {
-    const res = await this.client.get<{ data: Array<Document<any>> }>(
-      `/system/core/docs`,
-    );
-    const items = res.data?.data ?? [];
-    return {
-      data: items,
-      loading: false,
-      page: { number: 1, size: items.length, count: items.length, total: items.length, pages: 1 },
-    };
-  }
-
-  async read(_id: string): Promise<Document<any> | undefined> {
-    throw new Error("Read by ID not supported for capabilities; use find()")
-  }
-
-  async create(_props: { data: Partial<any> }): Promise<Document<any> | undefined> {
-    throw new Error("Capabilities are read-only")
-  }
-
-  async update(_props: { data: Partial<any>; options?: string }): Promise<Document<any> | undefined> {
-    throw new Error("Capabilities are read-only")
-  }
-
-  async delete(_id: string): Promise<void> {
-    throw new Error("Capabilities are read-only")
-  }
-
-  async list(_options?: Record<string, unknown>): Promise<Page<any>> {
-    return this.find()
-  }
-
-  async upload(_props: { file: File }): Promise<Document<any> | undefined> {
-    throw new Error("Upload not supported for capabilities")
-  }
-
-  async subscribe(_scope: string, _callback: (event: StoreEvent) => void): Promise<() => void> {
-    throw new Error("Subscription not supported for capabilities")
-  }
-
-  async notify(_event: StoreEvent): Promise<void> {
-    throw new Error("Notify not supported for capabilities")
-  }
-
-  stream(_options: Record<string, unknown>, _onStreamChange: () => void): {
-    stream: () => AsyncIterable<Document<any>>;
-    cancel: () => void;
-    status: () => "active" | "cancelled" | "completed";
-  } {
-    throw new Error("Stream not supported for capabilities")
-  }
-
-  page(_options?: Record<string, unknown>): PagedData<any> {
-    throw new Error("Pagination not supported for capabilities")
-  }
-}

package/system/capabilities/types.ts

@@ -1 +0,0 @@
-// Capabilities types — currently empty