akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/document/filterMeta.ts

@@ -18,9 +18,8 @@ import type { ConstantFilterMeta } from "./types";
 const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null;
 
-export const isFilterModel = (filterRef: Cls<unknown, { [FILTER_META]?: ConstantFilterMeta }>): boolean => {
-  return filterRef[FILTER_META] !== undefined;
-};
+export const isFilterModel = (filterRef: Cls<unknown, { [FILTER_META]?: ConstantFilterMeta }>): boolean =>
+  filterRef[FILTER_META] !== undefined;
 export const getFilterMeta = <AllowEmpty extends boolean = false>(
   filterRef: Cls<unknown, { [FILTER_META]?: ConstantFilterMeta }> | FilterCls,
   { allowEmpty = false as AllowEmpty }: { allowEmpty?: AllowEmpty } = {},
@@ -40,7 +39,7 @@ export const setFilterMeta = (
       .flatMap((sort) => Object.keys(sort)),
   );
   const existingFilterMeta = getFilterMeta(filterRef, { allowEmpty: true });
-  if (existingFilterMeta) {
+  if (existingFilterMeta)
     Object.assign(existingFilterMeta, {
       ...filterMeta,
       query: Object.assign(
@@ -54,29 +53,20 @@ export const setFilterMeta = (
         filterMeta.sort,
       ),
     });
-    sortField.forEach((field) => {
-      filterRef.sortField.add(field);
-    });
-  } else {
+  else
     Object.assign(filterRef, {
       [FILTER_META]: {
         query: Object.assign({}, ...libFilterMetas.map((libFilterMeta) => libFilterMeta.query), filterMeta.query),
         sort: Object.assign({}, ...libFilterMetas.map((libFilterMeta) => libFilterMeta.sort), filterMeta.sort),
       },
     });
-    sortField.forEach((field) => {
-      filterRef.sortField.add(field);
-    });
-  }
+  for (const field of sortField) filterRef.sortField.add(field);
 };
 export const getFilterInfoByKey = <ArgNames extends string[] = [], Args extends any[] = any[], Model = any>(
   modelRef: FilterCls,
   key: string,
 ): FilterInfo<ArgNames, Args, Model> => {
-  const filterMeta = getFilterMeta(
-    modelRef as Cls<unknown, { [FILTER_META]?: ConstantFilterMeta; sortField: Set<string> }>,
-  );
-  const queryMeta = filterMeta.query[key];
+  const queryMeta = getFilterMeta(modelRef).query[key];
   if (!queryMeta) throw new Error(`queryMeta is not defined for key: ${key}`);
   return queryMeta;
 };
@@ -88,12 +78,7 @@ export const setFilterInfoByKey = <ArgNames extends string[] = [], Args extends
   const filterMeta = getFilterMeta(modelRef);
   Object.assign(filterMeta.query, { [key]: filterInfo });
 };
-export const getFilterSortByKey = (modelRef: FilterCls, key: string) => {
-  const filterMeta = getFilterMeta(
-    modelRef as Cls<unknown, { [FILTER_META]?: ConstantFilterMeta; sortField: Set<string> }>,
-  );
-  return filterMeta.sort[key];
-};
+export const getFilterSortByKey = (modelRef: FilterCls, key: string) => getFilterMeta(modelRef).sort[key];
 
 export const fillMissingFilterArgs = (filterInfo: FilterInfo, args: unknown[]) => {
   if (args.length >= filterInfo.args.length) return args;
@@ -109,10 +94,7 @@ const isQueryOptionArg = (value: unknown) => {
   return Object.keys(value).every((key) => queryOptionKeys.has(key));
 };
 
-/**
- * Splits a generated filter method's arguments into the filter's own args and the trailing query option.
- * Shared by the database and service resolvers so the two cannot drift into disagreeing about what an option is.
- */
+/** Shared by the database and service resolvers, so the two cannot disagree about what a query option is. */
 export const splitFilterArgs = (filterInfo: FilterInfo, args: unknown[]) => {
   const hasQueryOption = args.length > filterInfo.args.length || isQueryOptionArg(args.at(-1));
   return {
@@ -158,10 +140,8 @@ const tryDeserializeFilterArg = (arg: FilterArgInfo, value: unknown, key: string
 };
 
 /**
- * Compiles a `(queryKey, args)` pair into the query its filter declares — the root slice's whole contract.
- * Every arg is parsed by the type the filter declared for it, so a Date arg reaches the query as a Dayjs and
- * an id that is not one is refused here rather than becoming a query that matches nothing. Args past the
- * declared ones are dropped: the caller names a filter, never a query.
+ * The root slice's contract: each arg is parsed by its declared type (an invalid id is refused rather than matching
+ * nothing), and args past the declared ones are dropped — the caller names a filter, never a query.
  */
 export const resolveFilterQuery = (
   filterRef: FilterCls,
@@ -224,7 +204,7 @@ interface BaseQuery<Model> {
 interface BaseSort {
   latest: { createdAt: -1 };
   oldest: { createdAt: 1 };
-
+  
   relevance: Record<string, never>;
 }
 type LibFilterQuery<LibFilters extends FilterCls[]> = MergeAllDoubleKeyOfObjects<

package/document/index.ts

@@ -9,5 +9,4 @@ export * from "./into";
 export * from "./loaderInfo";
 export * from "./noDocumentError";
 export * from "./queryEvaluator";
-export * from "./schema";
 export * from "./types";

package/document/into.ts

@@ -10,6 +10,7 @@ import type { DocumentProjection } from "./types";
 
 export type CRUDEventType = "create" | "update" | "remove";
 export type SaveEventType = "save" | CRUDEventType;
+export type SaveEventListener<Doc> = (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>;
 
 interface DefaultMdlStats<
   TDocument,
@@ -24,14 +25,8 @@ interface DefaultMdlStats<
   pickById: (docId: string | undefined, projection?: _Projection) => Promise<TDocument>;
   sample: (query: _FilterQuery, size?: number) => Promise<TDocument[]>;
   sampleOne: (query: _FilterQuery) => Promise<TDocument | null>;
-  listenPre: (
-    eventType: SaveEventType,
-    listener: (doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>,
-  ) => () => void;
-  listenPost: (
-    eventType: SaveEventType,
-    listener: (doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>,
-  ) => () => void;
+  listenPre: (eventType: SaveEventType, listener: SaveEventListener<TDocument>) => () => void;
+  listenPost: (eventType: SaveEventType, listener: SaveEventListener<TDocument>) => () => void;
 }
 export interface UpdateResult {
   acknowledged: boolean;
@@ -142,10 +137,7 @@ export const into = <
   cnst: IntoConstantModel<T, _CapitalizedRefName, Raw, Insight>,
   loaderBuilder: _LoaderBuilder,
   ...addMdls: [...AddDbModels]
-): ModelCls<
-  IntoModelActions<T, _CapitalizedRefName, Doc, Raw, Insight, _Query, _Sort, _QueryOfDoc>,
-  ReturnType<_LoaderBuilder>
-> => {
+) => {
   const loaderInfoMap = loaderBuilder(makeLoaderBuilder<Doc>());
   const libsOnSchemaFns = addMdls.map((mdl) => mdl._onSchema);
   const DefaultModel = Object.assign(class DefaultModel {}, {
@@ -157,12 +149,10 @@ export const into = <
     },
   });
   applyMixins(DefaultModel, addMdls);
-  addMdls.forEach((mdl) => {
-    Object.entries(Object.getOwnPropertyDescriptors(mdl)).forEach(([name, descriptor]) => {
-      if (["length", "name", "prototype"].includes(name)) return;
-      Object.defineProperty(DefaultModel, name, { ...descriptor, configurable: true });
-    });
-  });
+  for (const mdl of addMdls)
+    for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(mdl)))
+      if (!["length", "name", "prototype"].includes(name))
+        Object.defineProperty(DefaultModel, name, { ...descriptor, configurable: true });
   return DefaultModel as unknown as ModelCls<
     IntoModelActions<T, _CapitalizedRefName, Doc, Raw, Insight, _Query, _Sort, _QueryOfDoc>,
     ReturnType<_LoaderBuilder>

package/document/loaderInfo.ts

@@ -15,25 +15,46 @@ export type ModelCls<
     _libsOnSchema: (schema: SchemaOf<any, any>) => void;
   }
 >;
+export interface LoaderOption {
+  /** `false` by default; a number of milliseconds, or `true` for as long as the process runs. */
+  cache?: boolean | number;
+}
+
 export class LoaderInfo<Doc = any, Key extends keyof Doc = keyof Doc, QueryArg = Doc[Key]> {
   type: LoaderType;
   field: Key | Key[];
   defaultQuery: QueryOf<unknown>;
+  cache: boolean | number;
   queryArg: QueryArg | undefined;
-  constructor(type: LoaderType, field: Key | Key[], defaultQuery: QueryOf<unknown> = {}) {
+  constructor(
+    type: LoaderType,
+    field: Key | Key[],
+    defaultQuery: QueryOf<unknown> = {},
+    { cache = false }: LoaderOption = {},
+  ) {
     this.type = type;
     this.field = field;
     this.defaultQuery = defaultQuery;
+    this.cache = cache;
   }
 }
 
 export const makeLoaderBuilder = <Doc>() => ({
-  byField: <Key extends keyof Doc & string>(fieldName: Key, defaultQuery: QueryOf<unknown> = {}) =>
-    new LoaderInfo<Doc, Key>("field", fieldName, defaultQuery),
-  byArrayField: <Key extends keyof Doc & string>(fieldName: Key, defaultQuery: QueryOf<unknown> = {}) =>
-    new LoaderInfo<Doc, Key>("arrayField", fieldName, defaultQuery),
-  byQuery: <Key extends keyof Doc & string>(queryKeys: readonly Key[], defaultQuery: QueryOf<unknown> = {}) =>
-    new LoaderInfo<Doc, Key, Pick<Doc, Key>>("query", queryKeys as Key[], defaultQuery),
+  byField: <Key extends keyof Doc & string>(
+    fieldName: Key,
+    defaultQuery: QueryOf<unknown> = {},
+    option: LoaderOption = {},
+  ) => new LoaderInfo<Doc, Key>("field", fieldName, defaultQuery, option),
+  byArrayField: <Key extends keyof Doc & string>(
+    fieldName: Key,
+    defaultQuery: QueryOf<unknown> = {},
+    option: LoaderOption = {},
+  ) => new LoaderInfo<Doc, Key>("arrayField", fieldName, defaultQuery, option),
+  byQuery: <Key extends keyof Doc & string>(
+    queryKeys: readonly Key[],
+    defaultQuery: QueryOf<unknown> = {},
+    option: LoaderOption = {},
+  ) => new LoaderInfo<Doc, Key, Pick<Doc, Key>>("query", queryKeys as Key[], defaultQuery, option),
 });
 
 export type LoaderBuilder<Doc = any> = (builder: ReturnType<typeof makeLoaderBuilder<Doc>>) => {

package/document/noDocumentError.ts

@@ -1,11 +1,6 @@
 /**
- * A `pick` or a `get` that matched nothing. Typed so a caller can tell "you asked for something that is not
- * there" from "we broke" — an agent-facing transport in particular must not log a stack and answer "the server
- * failed" every time a model guesses an id.
- *
- * The message is unchanged from the bare `Error` this replaces, because callers already match on it, and the
- * `statusCode` does not reach the HTTP layer: `isExceptionLike` wants a `toJSON` too, so a missing document
- * stays a 500 there until someone decides framework-wide that it should be a 404.
+ * A `pick` or `get` that matched nothing, so a caller can tell a missing document from a failure. Callers match on
+ * the message; `statusCode` does not reach HTTP (`isExceptionLike` also wants a `toJSON`), where it stays a 500.
  */
 export class NoDocumentError extends Error {
   readonly statusCode = 404;

package/document/queryEvaluator.ts

@@ -9,11 +9,8 @@ import {
 } from "./documentQuery";
 
 /**
- * A document as the database stores it: base columns as written, everything else inside one JSON payload.
- *
- * Membership is evaluated against this rather than against a hydrated model because that is what the SQL the
- * evaluator has to agree with actually reads. A hydrated instance has already had defaults filled, dates turned
- * back into `Dayjs`, and absent optional keys materialized as `undefined` — every one of which changes an answer.
+ * A document as stored: base columns plus one JSON payload. Evaluated against this, not a hydrated model, whose filled
+ * defaults, `Dayjs` dates and materialized `undefined` keys would each change an answer the SQL gives.
  */
 export interface DocumentRowView {
   id: unknown;
@@ -36,13 +33,8 @@ interface PathValue {
 }
 
 /**
- * Answers "does this document match this query" in memory, reproducing what the SQL compiler would have asked the
- * database. Live sync routes a change to the rooms whose query it belongs to, and asking the database once per room
- * is not a thing that can be afforded on a write path.
- *
- * Every rule here mirrors a specific SQLite behaviour rather than a reasonable JavaScript reading of the same
- * operator, because the only property that matters is agreeing with `QueryCompiler` — a disagreement shows up as a
- * list that is quietly wrong, never as an error. `queryEvaluator.parity.test.ts` asks both and compares.
+ * Answers "does this document match this query" in memory for live sync, mirroring SQLite rather than JavaScript: a
+ * disagreement with `QueryCompiler` is a quietly wrong list, never an error (`queryEvaluator.parity.test.ts`).
  */
 export class DocumentQueryEvaluator {
   readonly #fields: QueryFieldMap;
@@ -52,17 +44,8 @@ export class DocumentQueryEvaluator {
   }
 
   /**
-   * Why this query cannot be evaluated in memory, or null when it can.
-   *
-   * Three things are genuinely out of reach. `raw` carries SQL only the database can run, and `search` compiles to
-   * an fts5 JOIN whose bm25 ranking has no in-memory equivalent. `exists`/`missing` on a `_doc` field ask whether
-   * the key is in the stored JSON at all, and a document read back has already had every declared nullable field
-   * materialized as `null` (`SqlDocumentStore.decodeDocumentPayload`) — so a value in hand cannot tell an absent
-   * key from a stored null, and answering anyway would be wrong for exactly the rows the operator exists to find.
-   * `empty` covers both cases and is evaluable, which is the operator the guide already directs callers to.
-   *
-   * Callers decide what to do about it — this reports, it does not throw, because refusing a boot is a policy the
-   * signal layer owns.
+   * Why a query cannot be evaluated in memory, or null: `raw` SQL, an fts5 `search`, or `exists`/`missing` on a
+   * `_doc` field (a read-back document has its nullable fields materialized as `null`). Refusing is the signal's call.
    */
   static unevaluableReason(query: DocumentQuery | undefined): string | null {
     if (!query || typeof query !== "object") return null;
@@ -99,17 +82,12 @@ export class DocumentQueryEvaluator {
   }
 
   /** Splits a saved document into the row shape above, mirroring `SqlDocumentStore.toRow`. */
-  static rowViewOf(doc: Record<string, unknown>): DocumentRowView {
-    const payload = { ...doc };
-    delete payload.id;
-    delete payload.createdAt;
-    delete payload.updatedAt;
-    delete payload.removedAt;
+  static rowViewOf({ id, createdAt, updatedAt, removedAt, ...payload }: Record<string, unknown>): DocumentRowView {
     return {
-      id: doc.id ?? null,
-      createdAt: doc.createdAt === undefined ? null : Number(encodeDocumentValue(doc.createdAt)),
-      updatedAt: doc.updatedAt === undefined ? null : Number(encodeDocumentValue(doc.updatedAt)),
-      removedAt: doc.removedAt ? Number(encodeDocumentValue(doc.removedAt)) : null,
+      id: id ?? null,
+      createdAt: createdAt === undefined ? null : Number(encodeDocumentValue(createdAt)),
+      updatedAt: updatedAt === undefined ? null : Number(encodeDocumentValue(updatedAt)),
+      removedAt: removedAt ? Number(encodeDocumentValue(removedAt)) : null,
       doc: (sanitizeJson(payload) ?? {}) as Record<string, unknown>,
     };
   }
@@ -217,7 +195,12 @@ export class DocumentQueryEvaluator {
         return this.#has(read, operand);
       case "contains":
         
-        return read.value !== null && String(read.value).toLowerCase().includes(String(operand).toLowerCase());
+        return (
+          read.value !== null &&
+          DocumentQueryEvaluator.#foldAscii(String(read.value)).includes(
+            DocumentQueryEvaluator.#foldAscii(String(operand)),
+          )
+        );
     }
   }
 
@@ -276,11 +259,6 @@ export class DocumentQueryEvaluator {
     return DocumentQueryEvaluator.#compare(value, DocumentQueryEvaluator.#encode(operand)) === 0;
   }
 
-  /**
-   * SQLite's ordering: NULL sorts below every number, which sorts below every text. Comparing across those classes
-   * is never equal, so a query on a field holding the wrong type matches nothing rather than coercing its way to a
-   * match the way JavaScript's `<` would.
-   */
   static #compare(left: unknown, right: unknown): number | null {
     const leftClass = DocumentQueryEvaluator.#classOf(left);
     const rightClass = DocumentQueryEvaluator.#classOf(right);
@@ -297,10 +275,6 @@ export class DocumentQueryEvaluator {
     return 2;
   }
 
-  /**
-   * By code point, which is exactly UTF-8 byte order and therefore SQLite's BINARY collation. JavaScript's own `<`
-   * compares UTF-16 code units, which puts supplementary-plane characters below U+E000 instead of above it.
-   */
   static #compareText(left: string, right: string): number {
     const leftPoints = [...left];
     const rightPoints = [...right];
@@ -313,6 +287,10 @@ export class DocumentQueryEvaluator {
     return leftPoints.length === rightPoints.length ? 0 : leftPoints.length < rightPoints.length ? -1 : 1;
   }
 
+  static #foldAscii(text: string) {
+    return text.replace(/[A-Z]/g, (char) => char.toLowerCase());
+  }
+
   static #isNode(value: unknown): value is DocumentQueryNode {
     return !!value && typeof value === "object" && "kind" in value;
   }

package/document/types.ts

@@ -39,4 +39,3 @@ export interface FindQueryOption<Sort = never, Obj = any> {
   sample?: boolean;
   select?: DocumentProjection<Obj>;
 }
-export type { SchemaOf } from "./documentSchema";