akanjs 2.0.5 → 2.0.7

package/signal/signalRegistry.ts

@@ -5,6 +5,18 @@ import type { ServerSignalCls } from "./serverSignal";
 import type { SliceCls } from "./slice";
 import type { SerializedSignal } from "./types";
 
+type SignalBaseRef<SigCls> = SigCls extends { srv: { srv: { refName: infer RefName } } } ? RefName : never;
+type SignalWithBase<RefName extends string, SigCls> = SignalBaseRef<SigCls> extends RefName ? SigCls : never;
+
+function assertSignalBase(refName: string, signalKind: string, signalCls: { srv?: { srv?: { refName?: unknown } } }) {
+  const signalRefName = signalCls.srv?.srv?.refName;
+  if (signalRefName !== refName) {
+    throw new Error(
+      `Signal base mismatch: ${signalKind} uses "${String(signalRefName)}", but registry expected "${refName}". Use srv.${refName}.with(...) when the signal needs another service.`,
+    );
+  }
+}
+
 export class DatabaseSignal<
   IntlCls extends InternalCls = InternalCls,
   EndpCls extends EndpointCls = EndpointCls,
@@ -46,34 +58,47 @@ export class ServiceSignal<
 
 /** Registry for database and service signals used by routing and fetch serialization. */
 export class SignalRegistry {
-  static readonly #database = new Map<string, DatabaseSignal<any, any, any, any>>();
-  static readonly #service = new Map<string, ServiceSignal<any, any, any>>();
+  static readonly #database = new Map<string, DatabaseSignal<InternalCls, EndpointCls, SliceCls, ServerSignalCls>>();
+  static readonly #service = new Map<string, ServiceSignal<InternalCls, EndpointCls, ServerSignalCls>>();
 
   static registerDatabase<
+    RefName extends string,
     IntlCls extends InternalCls,
     EndpCls extends EndpointCls,
     SlceCls extends SliceCls,
     SrvrCls extends ServerSignalCls,
   >(
-    internal: IntlCls,
-    endpoint: EndpCls,
-    slice: SlceCls,
+    refName: RefName,
+    internal: SignalWithBase<RefName, IntlCls>,
+    endpoint: SignalWithBase<RefName, EndpCls>,
+    slice: SignalWithBase<RefName, SlceCls>,
     server: SrvrCls,
   ): DatabaseSignal<IntlCls, EndpCls, SlceCls, SrvrCls> {
+    assertSignalBase(refName, "internal", internal);
+    assertSignalBase(refName, "endpoint", endpoint);
+    assertSignalBase(refName, "slice", slice);
     const databaseSignal = new DatabaseSignal(internal, endpoint, slice, server);
-    SignalRegistry.#database.set(internal.refName, databaseSignal);
+    SignalRegistry.#database.set(refName, databaseSignal);
     return databaseSignal;
   }
   static getDatabase(refName: string) {
     return SignalRegistry.#database.get(refName);
   }
-  static registerService<IntlCls extends InternalCls, EndpCls extends EndpointCls, SrvrCls extends ServerSignalCls>(
-    internal: IntlCls,
-    endpoint: EndpCls,
+  static registerService<
+    RefName extends string,
+    IntlCls extends InternalCls,
+    EndpCls extends EndpointCls,
+    SrvrCls extends ServerSignalCls,
+  >(
+    refName: RefName,
+    internal: SignalWithBase<RefName, IntlCls>,
+    endpoint: SignalWithBase<RefName, EndpCls>,
     server: SrvrCls,
   ): ServiceSignal<IntlCls, EndpCls, SrvrCls> {
+    assertSignalBase(refName, "internal", internal);
+    assertSignalBase(refName, "endpoint", endpoint);
     const serviceSignal = new ServiceSignal(internal, endpoint, server);
-    SignalRegistry.#service.set(internal.refName, serviceSignal);
+    SignalRegistry.#service.set(refName, serviceSignal);
     return serviceSignal;
   }
   static getService(refName: string) {

package/signal/trace.ts

@@ -0,0 +1,279 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Lightweight request tracing for Akan signals.
+ *
+ * Everything here is gated behind the `AKAN_TRACE=1` environment flag so that the
+ * production hot path pays nothing when tracing is disabled (see {@link isTraceEnabled}).
+ * The goal is internal performance work (per-stage latency breakdown, query counts,
+ * cache hit ratio) rather than full distributed tracing.
+ */
+
+let traceEnabledCache: boolean | null = null;
+
+/** Whether request tracing is enabled. Cached after first read. */
+export const isTraceEnabled = (): boolean => {
+  if (traceEnabledCache === null) traceEnabledCache = process.env.AKAN_TRACE === "1";
+  return traceEnabledCache;
+};
+
+/** Override the trace flag at runtime (tests / harness control). */
+export const setTraceEnabled = (enabled: boolean): void => {
+  traceEnabledCache = enabled;
+};
+
+export interface SpanRecord {
+  name: string;
+  durationMs: number;
+}
+
+const MAX_SPANS_PER_TRACE = 64;
+
+/** Per-request trace context. Threaded via {@link AsyncLocalStorage}. */
+export class SignalTrace {
+  readonly traceId: string;
+  readonly endpointKey: string;
+  readonly endpointType: string;
+  readonly startedAt: number;
+  readonly spans: SpanRecord[] = [];
+  dbQueryCount = 0;
+  dbQueryMs = 0;
+  cacheHits = 0;
+  cacheMisses = 0;
+  dataLoaderBatchCount = 0;
+  dataLoaderKeyCount = 0;
+  #finalized = false;
+
+  constructor(endpointKey: string, endpointType: string) {
+    this.endpointKey = endpointKey;
+    this.endpointType = endpointType;
+    this.startedAt = performance.now();
+    this.traceId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+
+  recordSpan(name: string, durationMs: number): void {
+    if (this.spans.length >= MAX_SPANS_PER_TRACE) return;
+    this.spans.push({ name, durationMs });
+  }
+
+  countDbQuery(durationMs: number): void {
+    this.dbQueryCount += 1;
+    this.dbQueryMs += durationMs;
+  }
+
+  countCache(hit: boolean): void {
+    if (hit) this.cacheHits += 1;
+    else this.cacheMisses += 1;
+  }
+
+  countDataLoaderBatch(keyCount: number): void {
+    this.dataLoaderBatchCount += 1;
+    this.dataLoaderKeyCount += keyCount;
+  }
+
+  finalize(): void {
+    if (this.#finalized) return;
+    this.#finalized = true;
+    const totalMs = performance.now() - this.startedAt;
+    this.recordSpan("total", totalMs);
+    traceAggregator.ingest(this);
+    maybeFlushTraceFile();
+  }
+}
+
+const traceProcessStore = process as unknown as {
+  __akanTraceAls?: AsyncLocalStorage<SignalTrace>;
+  __akanTraceAggregator?: TraceAggregator;
+};
+
+let alsInstance = traceProcessStore.__akanTraceAls;
+if (!alsInstance) {
+  alsInstance = new AsyncLocalStorage<SignalTrace>();
+  traceProcessStore.__akanTraceAls = alsInstance;
+}
+const als = alsInstance;
+
+export const getCurrentTrace = (): SignalTrace | undefined => als.getStore();
+
+/** Run `fn` with `trace` as the ambient request trace. */
+export const runWithTrace = <T>(trace: SignalTrace, fn: () => T): T => als.run(trace, fn);
+
+/**
+ * Time an async stage under the current trace. When tracing is off (or no trace is
+ * active) this is a thin passthrough with no measurement overhead.
+ */
+export const traceSpan = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
+  const trace = getCurrentTrace();
+  if (!trace) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    trace.recordSpan(name, performance.now() - start);
+  }
+};
+
+/** Record a DB query duration against the current trace (no-op when untraced). */
+export const traceDbQuery = (durationMs: number): void => {
+  getCurrentTrace()?.countDbQuery(durationMs);
+};
+
+/** Record a cache hit/miss against the current trace (no-op when untraced). */
+export const traceCache = (hit: boolean): void => {
+  getCurrentTrace()?.countCache(hit);
+};
+
+/** Record a DataLoader batch against the current trace (no-op when untraced). */
+export const traceDataLoaderBatch = (keyCount: number): void => {
+  getCurrentTrace()?.countDataLoaderBatch(keyCount);
+};
+
+interface SpanStat {
+  count: number;
+  sumMs: number;
+  maxMs: number;
+  samples: number[];
+}
+
+interface EndpointStat {
+  endpointKey: string;
+  endpointType: string;
+  requests: number;
+  spans: Map<string, SpanStat>;
+  dbQueryCount: number;
+  dbQueryMs: number;
+  cacheHits: number;
+  cacheMisses: number;
+  dataLoaderBatchCount: number;
+  dataLoaderKeyCount: number;
+}
+
+const RING_SIZE = 1024;
+
+const percentile = (sorted: number[], p: number): number => {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+  return sorted[idx] ?? 0;
+};
+
+/**
+ * Process-wide aggregator. Keeps rolling per-endpoint, per-span statistics with a
+ * bounded sample ring per span so percentiles stay representative of steady state
+ * without unbounded memory growth.
+ */
+class TraceAggregator {
+  #endpoints = new Map<string, EndpointStat>();
+
+  ingest(trace: SignalTrace): void {
+    const id = `${trace.endpointType}:${trace.endpointKey}`;
+    let stat = this.#endpoints.get(id);
+    if (!stat) {
+      stat = {
+        endpointKey: trace.endpointKey,
+        endpointType: trace.endpointType,
+        requests: 0,
+        spans: new Map(),
+        dbQueryCount: 0,
+        dbQueryMs: 0,
+        cacheHits: 0,
+        cacheMisses: 0,
+        dataLoaderBatchCount: 0,
+        dataLoaderKeyCount: 0,
+      };
+      this.#endpoints.set(id, stat);
+    }
+    stat.requests += 1;
+    stat.dbQueryCount += trace.dbQueryCount;
+    stat.dbQueryMs += trace.dbQueryMs;
+    stat.cacheHits += trace.cacheHits;
+    stat.cacheMisses += trace.cacheMisses;
+    stat.dataLoaderBatchCount += trace.dataLoaderBatchCount;
+    stat.dataLoaderKeyCount += trace.dataLoaderKeyCount;
+    for (const span of trace.spans) {
+      let spanStat = stat.spans.get(span.name);
+      if (!spanStat) {
+        spanStat = { count: 0, sumMs: 0, maxMs: 0, samples: [] };
+        stat.spans.set(span.name, spanStat);
+      }
+      spanStat.count += 1;
+      spanStat.sumMs += span.durationMs;
+      spanStat.maxMs = Math.max(spanStat.maxMs, span.durationMs);
+      if (spanStat.samples.length < RING_SIZE) spanStat.samples.push(span.durationMs);
+      else spanStat.samples[spanStat.count % RING_SIZE] = span.durationMs;
+    }
+  }
+
+  reset(): void {
+    this.#endpoints.clear();
+  }
+
+  /** Summarized snapshot suitable for JSON exposure on the metrics endpoint. */
+  snapshot() {
+    const endpoints = [...this.#endpoints.values()].map((stat) => {
+      const spans = [...stat.spans.entries()].map(([name, s]) => {
+        const sorted = [...s.samples].sort((a, b) => a - b);
+        return {
+          name,
+          count: s.count,
+          meanMs: round(s.sumMs / s.count),
+          p50Ms: round(percentile(sorted, 50)),
+          p95Ms: round(percentile(sorted, 95)),
+          p99Ms: round(percentile(sorted, 99)),
+          maxMs: round(s.maxMs),
+        };
+      });
+      spans.sort((a, b) => b.meanMs - a.meanMs);
+      const cacheTotal = stat.cacheHits + stat.cacheMisses;
+      return {
+        endpoint: `${stat.endpointType}:${stat.endpointKey}`,
+        requests: stat.requests,
+        avgDbQueriesPerRequest: round(stat.dbQueryCount / stat.requests),
+        avgDbQueryMsPerRequest: round(stat.dbQueryMs / stat.requests),
+        cacheHitRatio: cacheTotal ? round(stat.cacheHits / cacheTotal, 4) : null,
+        avgDataLoaderBatchSize: stat.dataLoaderBatchCount
+          ? round(stat.dataLoaderKeyCount / stat.dataLoaderBatchCount)
+          : null,
+        spans,
+      };
+    });
+    endpoints.sort((a, b) => b.requests - a.requests);
+    return { enabled: isTraceEnabled(), endpoints };
+  }
+}
+
+const round = (value: number, digits = 3): number => {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+};
+
+let aggregatorInstance = traceProcessStore.__akanTraceAggregator;
+if (!aggregatorInstance) {
+  aggregatorInstance = new TraceAggregator();
+  traceProcessStore.__akanTraceAggregator = aggregatorInstance;
+}
+export const traceAggregator: TraceAggregator = aggregatorInstance;
+
+/** Snapshot of all aggregated trace stats. Safe to call when tracing is disabled. */
+export const getTraceSnapshot = () => traceAggregator.snapshot();
+
+/**
+ * Optional file sink for the aggregated snapshot.
+ *
+ * The akan worker loads the app-server bundle and the framework metrics collector in
+ * separate module realms that share neither `globalThis` nor `process`, so the in-realm
+ * aggregator that records spans cannot be read by the metrics endpoint's collector. When
+ * `AKAN_TRACE_FILE` is set, the recording realm instead flushes the cumulative snapshot to
+ * that path (throttled), where any external reader (e.g. the benchmark harness) can pick it
+ * up. This is a benchmarking/diagnostics aid, not a production hot-path concern.
+ */
+const traceFilePath = process.env.AKAN_TRACE_FILE;
+let lastTraceFlushAt = 0;
+const TRACE_FLUSH_INTERVAL_MS = 1_000;
+
+const maybeFlushTraceFile = (): void => {
+  if (!traceFilePath) return;
+  const now = Date.now();
+  if (now - lastTraceFlushAt < TRACE_FLUSH_INTERVAL_MS) return;
+  lastTraceFlushAt = now;
+  void Bun.write(traceFilePath, JSON.stringify(traceAggregator.snapshot())).catch(() => {});
+};

package/types/cli/npmRegistry.d.ts

@@ -0,0 +1 @@
+export declare function getLatestPackageVersion(packageName: string, tag?: string): Promise<string>;

package/types/cli/openBrowser.d.ts

@@ -0,0 +1 @@
+export declare function openBrowser(url: string): Promise<void>;

package/types/cli/pluralizeName.d.ts

@@ -0,0 +1 @@
+export declare function pluralizeName(name: string): string;

package/types/cli/semver.d.ts

@@ -0,0 +1 @@
+export declare function compareSemver(a: string, b: string): number;

package/types/client/cookie.d.ts

@@ -1,9 +1,14 @@
 import type { Account } from "akanjs/fetch";
+interface CookieOptions {
+    path?: string;
+    sameSite?: "strict" | "lax" | "none";
+    secure?: boolean;
+}
 export declare const cookies: () => Map<string, {
     name: string;
     value: string;
 }>;
-export declare const setCookie: (key: string, value: string, options?: Cookies.CookieAttributes) => void;
+export declare const setCookie: (key: string, value: string, options?: CookieOptions) => void;
 export declare const getCookie: (key: string) => string | undefined;
 export declare const removeCookie: (key: string, options?: {
     path: string;

package/types/common/index.d.ts

@@ -11,6 +11,7 @@ export { isEmail } from "./isEmail.d.ts";
 export { isPhoneNumber } from "./isPhoneNumber.d.ts";
 export { isQueryEqual } from "./isQueryEqual.d.ts";
 export { isValidDate } from "./isValidDate.d.ts";
+export { decodeJwtPayload } from "./jwtDecode.d.ts";
 export { Logger, type LoggerSink, type LoggerSinkEntry, type LogLevel } from "./Logger.d.ts";
 export { type AkanI18nConfig, type AkanI18nConfigInput, DEFAULT_AKAN_I18N, parseAkanI18nEnv, resolveAkanI18nConfig, } from "./localeConfig.d.ts";
 export { lowerlize } from "./lowerlize.d.ts";

package/types/common/jwtDecode.d.ts

@@ -0,0 +1,2 @@
+/** Decodes a JWT payload without validating its signature. */
+export declare function decodeJwtPayload<T = unknown>(jwt: string): T;

package/types/devkit/capacitorApp.d.ts

@@ -8,6 +8,8 @@ interface RunConfig {
     env: "local" | "debug" | "develop" | "main";
     regenerate?: boolean;
 }
+interface PrepareConfig extends RunConfig {
+}
 export declare class CapacitorApp {
     #private;
     private readonly app;
@@ -18,19 +20,26 @@ export declare class CapacitorApp {
     };
     iosTargetName: string;
     readonly targetRoot: string;
+    readonly targetRootPath: string;
+    readonly targetWebRoot: string;
+    readonly targetAssetRoot: string;
+    readonly iosRootPath = "ios";
+    readonly iosProjectPath = "ios/App";
+    readonly androidRootPath = "android";
     constructor(app: AppExecutor, target: AkanMobileTargetConfig);
-    init({ platform, regenerate }?: {
+    init({ platform, operation, env, regenerate, }?: {
         platform?: "ios" | "android";
-        regenerate?: boolean;
-    }): Promise<this>;
+    } & Partial<PrepareConfig>): Promise<this>;
     save(): Promise<void>;
-    buildIos(options?: {
+    buildIos({ env, regenerate }?: {
+        env?: RunConfig["env"];
         regenerate?: boolean;
     }): Promise<void>;
     syncIos(): Promise<void>;
     openIos(): Promise<void>;
     runIos({ operation, env, regenerate }: RunConfig): Promise<void>;
-    buildAndroid(assembleType: "apk" | "aab", options?: {
+    buildAndroid(assembleType: "apk" | "aab", { env, regenerate }?: {
+        env?: RunConfig["env"];
         regenerate?: boolean;
     }): Promise<void>;
     openAndroid(): Promise<void>;

package/types/devkit/incrementalBuilder/incrementalBuilder.host.d.ts

@@ -7,6 +7,12 @@ interface IncrementalBuilderHostOptions {
     env: Record<string, string>;
     onMessage: (message: BuilderMessage) => void;
 }
+type IncrementalBuilderStatus = "starting" | "ready" | "restarting" | "stopped";
+interface IncrementalBuilderStartOptions {
+    onExit?: () => void;
+    onReady?: () => void;
+    onRestartReady?: () => void;
+}
 export declare class IncrementalBuilderHost {
     #private;
     logger: Logger;
@@ -15,11 +21,9 @@ export declare class IncrementalBuilderHost {
     app: App;
     ready: boolean;
     constructor({ app, entry, env, onMessage }: IncrementalBuilderHostOptions);
-    start({ onExit, onReady }: {
-        onExit?: () => void;
-        onReady?: () => void;
-    }): this;
-    send(message: BuilderMessage): void;
+    get status(): IncrementalBuilderStatus;
+    start(options?: IncrementalBuilderStartOptions): this;
+    send(message: BuilderMessage): boolean;
     stop(): void;
     static create(app: App, env: Record<string, string>, onMessage: (message: BuilderMessage) => void): Promise<IncrementalBuilderHost>;
 }

package/types/document/dataLoader.d.ts

@@ -1,17 +1,36 @@
 import type { QueryOf } from "akanjs/constant";
-import DataLoader from "dataloader";
 export declare const Id: StringConstructor;
 export declare const ObjectId: StringConstructor;
 export declare const Mixed: ObjectConstructor;
-export { DataLoader };
 type LoaderItem = Record<string, unknown>;
 type LoaderModel = {
     find: (query: QueryOf<unknown>) => Promise<LoaderItem[]> | {
         then: Promise<LoaderItem[]>["then"];
     };
 };
+type BatchLoadFn<Key, Value> = (keys: readonly Key[]) => PromiseLike<ReadonlyArray<Value | Error>> | ReadonlyArray<Value | Error>;
+interface DataLoaderOptions<Key, CacheKey> {
+    cache?: boolean;
+    cacheKeyFn?: (key: Key) => CacheKey;
+    batch?: boolean;
+    batchScheduleFn?: (callback: () => void) => void;
+    maxBatchSize?: number;
+    name?: string;
+}
+/** Minimal DataLoader-compatible batch loader used by Akan document resolvers. */
+export declare class DataLoader<Key, Value, CacheKey = Key> {
+    #private;
+    readonly name?: string;
+    constructor(batchLoadFn: BatchLoadFn<Key, Value>, options?: DataLoaderOptions<Key, CacheKey>);
+    load(key: Key): Promise<Value>;
+    loadMany(keys: readonly Key[]): Promise<Array<Value | Error>>;
+    clear(key: Key): this;
+    clearAll(): this;
+    prime(key: Key, value: Value | Error): this;
+}
 export declare const createLoader: <Key, Value>(model: LoaderModel, fieldName?: string, defaultQuery?: QueryOf<unknown>) => DataLoader<Key, Value, Key>;
 export declare const createArrayLoader: <K, V>(model: LoaderModel, fieldName?: string, defaultQuery?: QueryOf<unknown>) => DataLoader<K, V, K>;
 export declare const createArrayElementLoader: <K, V>(model: LoaderModel, fieldName?: string, defaultQuery?: QueryOf<unknown>) => DataLoader<K, V, K>;
 export declare const createQueryLoader: <Key, Value>(model: LoaderModel, queryKeys: string[], defaultQuery?: QueryOf<unknown>) => DataLoader<Key, Value, Key>;
 export type Loader<Field, Value> = DataLoader<Field, Value | null>;
+export {};

package/types/document/database.d.ts

@@ -2,7 +2,7 @@ import type { Dayjs, MergedValues, PromiseOrObject } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { CacheAdaptor } from "akanjs/service";
-import type DataLoader from "dataloader";
+import type { DataLoader } from "./dataLoader.d.ts";
 import type { ExtractQuery, ExtractSort, FilterInstance } from "./filterMeta.d.ts";
 import type { CRUDEventType, Mdl, SaveEventType } from "./into.d.ts";
 import type { DataInputOf, FindQueryOption, ListQueryOption } from "./types.d.ts";

package/types/server/processMetricsCollector.d.ts

@@ -2,6 +2,8 @@ import type { AkanMetricsReport } from "akanjs/service";
 export declare class ProcessMetricsCollector {
     #private;
     static parseMemoryLogIntervalMs(value?: string | undefined): number;
+    /** Begin sampling event-loop lag. Idempotent; safe to call from each server role. */
+    static startEventLoopLagMonitor(intervalMs?: number): void;
     static collect(extra?: AkanMetricsReport): Promise<AkanMetricsReport>;
     static formatBytes(bytes?: number): string;
     static format(metrics: AkanMetricsReport): string;

package/types/service/ipcTypes.d.ts

@@ -108,6 +108,11 @@ export interface AkanMetricsReport {
     httpHtmlCacheHits?: number;
     httpHtmlCacheMisses?: number;
     httpHtmlCacheBypass?: number;
+    eventLoopLagMeanMs?: number;
+    eventLoopLagP99Ms?: number;
+    eventLoopLagMaxMs?: number;
+    gcDurationMs?: number;
+    trace?: unknown;
 }
 export type AkanIpcMessage = {
     type: "ready";

package/types/service/predefinedAdaptor/database.adaptor.d.ts

@@ -67,33 +67,20 @@ export interface DocumentStore {
         modifiedCount: number;
         upsertedId: string | null;
     }>;
-    find(query?: DocumentQuery, options?: {
-        sort?: SortOption;
-        skip?: number | null;
-        limit?: number | null;
-        sample?: number;
-    }): Promise<any[]>;
+    find(query?: DocumentQuery, options?: FindManyOptions): Promise<any[]>;
     findIds(query?: DocumentQuery, options?: {
         sort?: SortOption;
         skip?: number | null;
         limit?: number | null;
         sample?: number;
     }): Promise<string[]>;
-    findOne(query?: DocumentQuery, options?: {
-        sort?: SortOption;
-        skip?: number | null;
-        sample?: boolean;
-    }): Promise<any | null>;
+    findOne(query?: DocumentQuery, options?: FindOneOptions): Promise<any | null>;
     findId(query?: DocumentQuery, options?: {
         sort?: SortOption;
         skip?: number | null;
         sample?: boolean;
     }): Promise<string | null>;
-    pickOne(query?: DocumentQuery, options?: {
-        sort?: SortOption;
-        skip?: number | null;
-        sample?: boolean;
-    }): Promise<any>;
+    pickOne(query?: DocumentQuery, options?: FindOneOptions): Promise<any>;
     pickById(id: string): Promise<any>;
     exists(query?: DocumentQuery): Promise<string | null>;
     count(query?: DocumentQuery): Promise<number>;
@@ -128,6 +115,20 @@ type FieldMap = Record<string, {
     [key: string]: unknown;
 }>;
 type SortOption = Record<string, 1 | -1> | null | undefined;
+type ProjectionOption = Partial<Record<string, boolean>> | null | undefined;
+type FindManyOptions = {
+    sort?: SortOption;
+    skip?: number | null;
+    limit?: number | null;
+    sample?: number;
+    select?: ProjectionOption;
+};
+type FindOneOptions = {
+    sort?: SortOption;
+    skip?: number | null;
+    sample?: boolean;
+    select?: ProjectionOption;
+};
 interface DocumentDatabaseOwner {
     getConnection(): AkanSqlClient;
     getMeta(key: string): Promise<string | undefined> | string | undefined;
@@ -214,33 +215,20 @@ export declare class SqliteDocumentStore {
         modifiedCount: number;
         upsertedId: string | null;
     }>;
-    find(query?: DocumentQuery, options?: {
-        sort?: SortOption;
-        skip?: number | null;
-        limit?: number | null;
-        sample?: number;
-    }): Promise<any[]>;
+    find(query?: DocumentQuery, options?: FindManyOptions): Promise<any[]>;
     findIds(query?: DocumentQuery, options?: {
         sort?: SortOption;
         skip?: number | null;
         limit?: number | null;
         sample?: number;
     }): Promise<string[]>;
-    findOne(query?: DocumentQuery, options?: {
-        sort?: SortOption;
-        skip?: number | null;
-        sample?: boolean;
-    }): Promise<any>;
+    findOne(query?: DocumentQuery, options?: FindOneOptions): Promise<any>;
     findId(query?: DocumentQuery, options?: {
         sort?: SortOption;
         skip?: number | null;
         sample?: boolean;
     }): Promise<string | null>;
-    pickOne(query?: DocumentQuery, options?: {
-        sort?: SortOption;
-        skip?: number | null;
-        sample?: boolean;
-    }): Promise<any>;
+    pickOne(query?: DocumentQuery, options?: FindOneOptions): Promise<any>;
     pickById(id: string): Promise<any>;
     exists(query?: DocumentQuery): Promise<string | null>;
     count(query?: DocumentQuery): Promise<number>;
@@ -259,6 +247,11 @@ export declare class SqliteDocumentStore {
     private applyDocumentUpdate;
     private toRow;
     private fromRow;
+    private normalizeProjection;
+    private projectionSql;
+    private projectionAlias;
+    private fromProjectedRow;
+    private parseProjectedValue;
     private decodeDocumentPayload;
     private decodeFieldValue;
     private decodeMapValue;
@@ -266,6 +259,7 @@ export declare class SqliteDocumentStore {
     hydrate(data: DocumentRecord, originalData?: DocumentRecord): any;
     private runHooks;
     private insertStmt;
+    private prepareReadStmt;
     private assertValidRefName;
 }
 declare const SqliteDatabase_base: import("..").AdaptorCls<{}, {

package/types/service/predefinedAdaptor/solidSqlite.d.ts

@@ -13,12 +13,12 @@ export interface SolidEnv extends BaseEnv {
     workspaceRoot?: string;
     solid?: SolidConfig;
 }
-export type SolidValueType = "string" | "number" | "buffer";
+export type SolidValueType = "string" | "number" | "buffer" | "json";
 export declare const getSolidConfig: (env: SolidEnv) => Required<SolidConfig>;
 export declare const openSolidDatabase: (config: Required<SolidConfig>) => Promise<Database>;
-export declare const encodeSolidValue: (value: string | number | Buffer) => {
+export declare const encodeSolidValue: (value: unknown) => {
     type: SolidValueType;
     value: string | Buffer;
 };
-export declare const decodeSolidValue: <T extends string | number | Buffer>(type: SolidValueType, value: string | Buffer | null) => T | undefined;
+export declare const decodeSolidValue: <T>(type: SolidValueType, value: string | Buffer | null) => T | undefined;
 export declare const toEpochMs: (value?: Dayjs | number | null) => number | null;