akanjs 2.4.1 → 2.4.2-rc.1

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

@@ -0,0 +1,73 @@
+import { type ConstantModel, textFieldRoles } from "akanjs/constant";
+import { type DatabaseModel, type SearchColumn } from "akanjs/document";
+import type { AkanSqlClient } from "./database.adaptor";
+export declare const DOC_TABLE = "search_doc";
+export declare const FTS_TABLE = "search_fts";
+export declare const DEFAULT_TOKENIZER = "unicode61 remove_diacritics 2";
+export declare const OPTIMIZE_CRON_KEY = "searchIndexOptimize";
+export declare const OPTIMIZE_CRON = "17 4 * * *";
+export declare const RETRY_INTERVAL_KEY = "searchIndexRetry";
+export declare const RETRY_INTERVAL_MS = 60000;
+export declare const DEFAULT_SEARCH_WEIGHTS: number[];
+export interface SearchIndexOwner {
+    getConnection(): AkanSqlClient;
+    getMeta(key: string): Promise<string | undefined> | string | undefined;
+    setMeta(key: string, value: string): Promise<void>;
+}
+export interface SearchIndexOptions {
+    enabled: boolean;
+    tokenizer: string;
+}
+type SearchColumns = Record<(typeof textFieldRoles)[number], string>;
+/**
+ * Reads `AKAN_SEARCH_ENABLED`. Unset means enabled; an unrecognised value fails the boot rather than
+ * silently falling back, because a typo like `ture` would otherwise look identical to the default.
+ */
+export declare const parseSearchEnabled: (value: string | undefined) => boolean;
+/**
+ * Turns raw user input into an fts5 MATCH expression.
+ *
+ * Raw text cannot be passed through: `-`, `:`, `*`, `"` and a trailing `AND` are all fts5 syntax and each
+ * raises `SQLiteError` instead of returning no rows. Quoting every term makes the whole input literal.
+ */
+export declare const toMatchExpression: (text: string, { prefix, columns }?: {
+    prefix?: boolean;
+    columns?: readonly SearchColumn[];
+}) => string | null;
+/**
+ * Owns the `search_doc` mirror and its fts5 index.
+ *
+ * The mirror is maintained by SQL triggers rather than document hooks because `updateOneByQuery` and friends
+ * deliberately fire no hooks — most searchable-field mutations go through exactly that path, so an app-level
+ * hook would miss them silently.
+ */
+export declare class SearchIndex {
+    #private;
+    constructor(owner: SearchIndexOwner, { enabled, tokenizer }: SearchIndexOptions);
+    get enabled(): boolean;
+    ensureSchema(): Promise<void>;
+    /** Returns whether this ref's mirror is now current. `false` means another process is rebuilding it. */
+    ensureRef(constant: ConstantModel, database: DatabaseModel): Promise<boolean>;
+    /** Re-runs the refs another process was holding. Returns how many are still outstanding. */
+    retryPending(): Promise<number>;
+    /**
+     * Rebuilds one ref's mirror rows in id-ordered chunks so a large table does not block the boot. `onChunk` runs
+     * between chunks and reports whether this process still holds the claim: a backfill that outlives the lock TTL
+     * would otherwise keep writing rows underneath the `DELETE` of the process that took over. Returns whether the
+     * whole table was covered.
+     */
+    reconcileRef(ref: string, columns: SearchColumns, onChunk?: () => Promise<boolean>): Promise<boolean>;
+    /** Merges accumulated fts5 segments. Returns whether this process was the one that did the work. */
+    optimize(): Promise<boolean>;
+    /**
+     * Drops a ref's triggers so a bulk import skips the per-row mirror write. Pair with `resume`.
+     *
+     * The hash is cleared here rather than in `resume` alone: a process that dies mid-import never reaches `resume`,
+     * and a boot that finds the hash intact recreates the triggers and skips the backfill, leaving everything
+     * written in between missing from the mirror for good.
+     */
+    suspend(database: DatabaseModel): Promise<void>;
+    /** Returns whether the mirror is current again; `false` means another process holds the rebuild. */
+    resume(constant: ConstantModel, database: DatabaseModel): Promise<boolean>;
+}
+export {};

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

@@ -0,0 +1,5 @@
+export declare const quoteIdent: (identifier: string) => string;
+export declare const jsonPath: (path: string) => string;
+export declare const stableJson: (value: unknown) => string;
+/** Stable hash of a schema descriptor, stored in `_akan_meta` so a changed definition is detected without migrations. */
+export declare const descriptorHash: (value: unknown) => Promise<string>;

package/types/signal/signalContext.d.ts

@@ -32,6 +32,12 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     getAdaptor<T extends Adaptor>(adaptorCls: AdaptorCls<T>): T;
     getService<T>(refName: string): T;
     init(): Promise<this>;
+    /**
+     * Re-checks this context's guards outside of a request, for a websocket room that is already
+     * subscribed. Only global middlewares run: they carry the account resolution this depends on,
+     * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
+     */
+    authorize(): Promise<boolean>;
     exec(): Promise<Response | undefined>;
     static try(endpoint: Adaptor, endpointInfo: EndpointInfo, key: string, fn: () => Promise<Response | undefined>): Promise<Response | undefined>;
     static resolveReturn(value: unknown, { signalContext, returnRef, arrDepth, registry, live, }: {
@@ -47,6 +53,7 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     }): Promise<unknown>;
     getHttpContext<Appended = unknown>(): HttpExecutionContext<Appended>;
     getWebSocketContext<Appended = unknown>(): WebSocketExecutionContext<Appended>;
+    get<T = unknown>(key: string): T | null;
     getRoomId(key: string): string;
     getEnv(): Env;
     getArg<T = unknown>(argName: string): T | undefined;

package/types/signal/types.d.ts

@@ -147,5 +147,9 @@ export type WebsocketPublishData = {
     roomId: string;
     data: object | object[];
 };
-export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData;
+export type WebsocketAuthAck = {
+    type: "auth";
+    revokedRooms: string[];
+};
+export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData | WebsocketAuthAck;
 export {};

package/types/ui/Constant/schemaDoc.d.ts

@@ -1,5 +1,5 @@
 import { type EnumInstance } from "akanjs/base";
-import { type ConstantCls, type ConstantField } from "akanjs/constant";
+import { type ConstantCls, type ConstantField, type TextFieldRole } from "akanjs/constant";
 export declare const databaseModelVariants: readonly ["input", "object", "full", "light", "insight"];
 export type DatabaseModelVariant = (typeof databaseModelVariants)[number];
 export interface ConstantSchemaOptions {
@@ -75,7 +75,7 @@ export interface FieldSchema {
     defaultLabel?: string;
     exampleLabel?: string;
     constraints: string[];
-    text?: "search" | "filter";
+    text?: TextFieldRole;
     meta: Record<string, unknown>;
     raw: ConstantField;
 }

package/ui/Constant/schemaDoc.ts

@@ -7,7 +7,13 @@ import {
   type PrimitiveScalar,
 } from "akanjs/base";
 import { capitalize } from "akanjs/common";
-import { type ConstantCls, type ConstantField, type ConstantModel, ConstantRegistry } from "akanjs/constant";
+import {
+  type ConstantCls,
+  type ConstantField,
+  type ConstantModel,
+  ConstantRegistry,
+  type TextFieldRole,
+} from "akanjs/constant";
 
 export const databaseModelVariants = ["input", "object", "full", "light", "insight"] as const;
 export type DatabaseModelVariant = (typeof databaseModelVariants)[number];
@@ -93,7 +99,7 @@ export interface FieldSchema {
   defaultLabel?: string;
   exampleLabel?: string;
   constraints: string[];
-  text?: "search" | "filter";
+  text?: TextFieldRole;
   meta: Record<string, unknown>;
   raw: ConstantField;
 }

package/ui/Model/EditModal.tsx

@@ -1,5 +1,5 @@
 "use client";
-import { clsx, router, usePage } from "akanjs/client";
+import { clsx, isRscNavigationFromCache, router, usePage } from "akanjs/client";
 import { capitalize, deepObjectify, lowerlize } from "akanjs/common";
 import { ConstantRegistry, immerify } from "akanjs/constant";
 import type { ClientEdit, ServerEdit, SliceMeta } from "akanjs/fetch";
@@ -11,6 +11,8 @@ import { AiOutlinePlus, AiOutlineSave } from "react-icons/ai";
 import { Button } from "../Button";
 import { Modal } from "../Modal";
 
+const EDIT_PAYLOAD_MAX_AGE_MS = 60_000;
+
 interface EditModelProps<Full> {
   /** Rendering mode for the edit shell. */
   type?: "modal" | "form" | "empty";
@@ -148,6 +150,7 @@ export default function EditModal<Full extends { id: string }>({
       setModelModal: `set${ModelName}Modal`,
       modelLoading: `${modelName}Loading`,
       modelViewAt: `${modelName}ViewAt`,
+      editModel: `edit${ModelName}`,
       newModel: `new${ModelName}`,
       crystalizeModel: `crystalize${ModelName}`,
       modelObj: `${modelName}Obj`,
@@ -159,10 +162,19 @@ export default function EditModal<Full extends { id: string }>({
     (state: unknown) => (state as { [key: string]: { id: string | null } })[names.modelForm].id,
   );
   const modelFormLoading = storeUse[names.modelFormLoading]() as string | boolean;
+  const modalId = id ?? ((modelEdit as any)?.[names.modelObj] as Full | undefined)?.id ?? undefined;
   const isModalOpen =
     modelModal === (modal ?? "edit") &&
-    (modelFormLoading === false || modelFormLoading === id) &&
-    ((!modelFormId && !id) || id === modelFormId);
+    (modelFormLoading === false || modelFormLoading === modalId) &&
+    ((!modelFormId && !modalId) || modalId === modelFormId);
+  const isEditPayloadStale = useCallback((viewAt?: Date | null) => {
+    if (isRscNavigationFromCache()) return true;
+    return (
+      viewAt instanceof Date &&
+      !Number.isNaN(viewAt.getTime()) &&
+      Date.now() - viewAt.getTime() > EDIT_PAYLOAD_MAX_AGE_MS
+    );
+  }, []);
   useEffect(() => {
     if (!modelEdit) return;
     const refName = (modelEdit as ServerEdit<string, Full>).refName;
@@ -170,15 +182,21 @@ export default function EditModal<Full extends { id: string }>({
     const cnst = ConstantRegistry.getDatabase(modelName);
     const modelRef = cnst.full;
     if (editType === "edit") {
-      const crystal = new modelRef().set((modelEdit as any)[names.modelObj] as Full) as unknown as Full;
+      const modelObj = (modelEdit as any)[names.modelObj] as Full;
+      const viewAt = (modelEdit as any)[names.modelViewAt] as Date;
+      const crystal = new modelRef().set(modelObj) as unknown as Full;
       st.set({
         [names.model]: crystal,
         [names.modelLoading]: false,
         [names.modelForm]: immerify(modelRef, crystal),
         [names.modelFormLoading]: false,
         [names.modelModal]: modal ?? "edit",
-        [names.modelViewAt]: (modelEdit as any)[names.modelViewAt] as Date,
+        [names.modelViewAt]: viewAt,
       });
+      if (isEditPayloadStale(viewAt))
+        void storeDo[names.editModel](modelObj.id, { modal }).catch(() => {
+          st.set({ [names.modelFormLoading]: false });
+        });
     } else {
       
       const crystal = new modelRef().set(modelEdit as Full) as unknown as Full;
@@ -186,7 +204,7 @@ export default function EditModal<Full extends { id: string }>({
     }
     return () => {
     };
-  }, [modelEdit]);
+  }, [modelEdit, isEditPayloadStale]);
 
   const handleCancel = useCallback(() => {
     const modelForm = (st.get() as any)[names.modelForm] as Full;