akanjs 2.3.11-rc.0 → 2.3.11-rc.10

package/client/capacitor.ts

@@ -107,6 +107,19 @@ export type CapacitorPushNotificationsModule = {
     requestPermissions: () => Promise<{ receive: "granted" | "denied" | string }>;
     checkPermissions: () => Promise<{ receive: "granted" | "denied" | string }>;
     register: () => Promise<void> | void;
+    addListener: (
+      eventName:
+        | "registration"
+        | "registrationError"
+        | "pushNotificationReceived"
+        | "pushNotificationActionPerformed"
+        | string,
+      listenerFunc: (event: {
+        value?: string;
+        error?: string;
+        notification?: { data?: Record<string, unknown> };
+      }) => void,
+    ) => Promise<{ remove?: () => Promise<void> | void } | void> | { remove?: () => Promise<void> | void } | void;
   };
 };
 

package/client/csrTypes.ts

@@ -191,6 +191,8 @@ export interface Route {
   path: string;
   renderPage?: RouteRender;
   renderLayout?: RouteRender;
+  /** Synthetic layout render from a `_overrides.tsx` at this node; wraps the subtree in a UI-override provider. */
+  renderOverrides?: RouteRender;
   pageIncludesOwnLayout?: boolean;
   isSpecialRoute?: boolean;
 

package/common/routeConvention.ts

@@ -1,11 +1,13 @@
 const ROUTE_SOURCE_RE = /^\.\/(.+)\.(tsx|ts|jsx|js)$/;
 const SOURCE_EXT_RE = /\.(tsx|ts|jsx|js)$/;
-const RESERVED_ROUTE_FILES = new Set(["_layout", "_index"]);
+const RESERVED_ROUTE_FILES = new Set(["_layout", "_index", "_overrides"]);
 const INTERNAL_ROOT_LAYOUT_LEAF = "__root_layout";
 const IMPLICIT_LOCALE_SEGMENT = "[lang]";
 const SPECIAL_ROUTE_LEAVES = new Set(["robots.txt"]);
 
-export type RouteModuleKind = "page" | "layout";
+const DIRECTORY_SCOPED_LEAVES = new Set(["_layout", "_index", "_overrides"]);
+
+export type RouteModuleKind = "page" | "layout" | "overrides";
 
 export interface ParsedRouteModuleKey {
   key: string;
@@ -51,7 +53,7 @@ export function validatePageSourceFile(filePath: string, options: ValidatePageSo
   if (ext !== "tsx") throw new Error(`[route-convention] route source files under page/ must use .tsx: ${displayPath}`);
   if (leaf.startsWith("_") && !RESERVED_ROUTE_FILES.has(leaf) && leaf !== INTERNAL_ROOT_LAYOUT_LEAF)
     throw new Error(
-      `[route-convention] only _index.tsx and _layout.tsx are allowed as reserved route files under page/: ${displayPath}`,
+      `[route-convention] only _index.tsx, _layout.tsx and _overrides.tsx are allowed as reserved route files under page/: ${displayPath}`,
     );
   if (/^[A-Z]/.test(leaf))
     throw new Error(`[route-convention] route page filenames must not start with an uppercase letter: ${displayPath}`);
@@ -97,13 +99,14 @@ export function parseRouteModuleKey(key: string): ParsedRouteModuleKey {
   }
 
   const isInternalRootLayout = leaf === INTERNAL_ROOT_LAYOUT_LEAF;
-  const kind: RouteModuleKind = leaf === "_layout" || isInternalRootLayout ? "layout" : "page";
+  const kind: RouteModuleKind =
+    leaf === "_layout" || isInternalRootLayout ? "layout" : leaf === "_overrides" ? "overrides" : "page";
   if (leaf.startsWith("_") && !RESERVED_ROUTE_FILES.has(leaf) && !isInternalRootLayout) {
     throw new Error(`[route-convention] unsupported reserved route file "${leaf}" in ${key}`);
   }
 
   const sourceRouteSegments =
-    leaf === "_layout" || leaf === "_index" || isInternalRootLayout ? moduleSegments.slice(0, -1) : moduleSegments;
+    DIRECTORY_SCOPED_LEAVES.has(leaf) || isInternalRootLayout ? moduleSegments.slice(0, -1) : moduleSegments;
   const isSpecialRoute = kind === "page" && SPECIAL_ROUTE_LEAVES.has(leaf);
   const routeSegments = isSpecialRoute ? sourceRouteSegments : [IMPLICIT_LOCALE_SEGMENT, ...sourceRouteSegments];
   for (const segment of routeSegments) validateRouteSegment(segment, key);

package/document/documentQuery.ts

@@ -53,21 +53,67 @@ export type DocumentQueryValue =
   | undefined
   | Record<string, unknown>;
 
-export interface DocumentUpdate {
-  [key: string]: unknown;
-  set?: Record<string, unknown>;
-  unset?: Record<string, unknown> | string[];
-  addToSet?: Record<string, unknown>;
-  pull?: Record<string, unknown>;
-  push?: Record<string, unknown>;
-  inc?: Record<string, number>;
-  setOnInsert?: Record<string, unknown>;
+export type DocumentUpdateOperator =
+  | "set"
+  | "unset"
+  | "inc"
+  | "mul"
+  | "min"
+  | "max"
+  | "push"
+  | "pull"
+  | "addToSet"
+  | "setOnInsert";
+
+export interface DocumentUpdateNode {
+  kind: "update";
+  op: DocumentUpdateOperator;
+  value?: unknown;
 }
 
+export type DocumentUpdateValue =
+  | DocumentUpdateNode
+  | DocumentPrimitive
+  | DocumentPrimitive[]
+  | Record<string, unknown>
+  | undefined;
+
+export type DocumentUpdate<T = any> = {
+  [K in DocumentPath<T>]?: DocumentUpdateValue;
+};
+
 export interface DocumentUpdateOptions {
   upsert?: boolean;
 }
 
+const updateOp = (op: DocumentUpdateOperator, value?: unknown): DocumentUpdateNode => ({ kind: "update", op, value });
+
+export const createDocumentUpdateHelper = () => ({
+  set: (value: unknown) => updateOp("set", value),
+  unset: () => updateOp("unset"),
+  inc: (by = 1) => updateOp("inc", by),
+  mul: (by: number) => updateOp("mul", by),
+  min: (value: unknown) => updateOp("min", value),
+  max: (value: unknown) => updateOp("max", value),
+  push: (value: unknown) => updateOp("push", value),
+  pull: (value: unknown) => updateOp("pull", value),
+  addToSet: (value: unknown) => updateOp("addToSet", value),
+  setOnInsert: (value: unknown) => updateOp("setOnInsert", value),
+});
+
+export type DocumentUpdateHelper = ReturnType<typeof createDocumentUpdateHelper>;
+
+export const documentUpdateHelper = createDocumentUpdateHelper();
+
+export type DocumentUpdateBuilder<T = any> = (helper: DocumentUpdateHelper) => DocumentUpdate<T>;
+export type DocumentUpdateInput<T = any> = DocumentUpdate<T> | DocumentUpdateBuilder<T>;
+
+export const resolveDocumentUpdate = <T>(update: DocumentUpdateInput<T>): DocumentUpdate<T> =>
+  typeof update === "function" ? update(documentUpdateHelper) : update;
+
+export const isDocumentUpdateNode = (value: unknown): value is DocumentUpdateNode =>
+  !!value && typeof value === "object" && (value as { kind?: unknown }).kind === "update";
+
 export type DocumentQuery<T = any> =
   | DocumentQueryNode
   | {

package/document/into.ts

@@ -4,7 +4,7 @@ import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { FilterCls, FilterQueryOf, FilterSortOf, SchemaOf } from ".";
 import type { CacheDatabase, QueryMethodPart } from "./database";
 import type { DataLoader } from "./dataLoader";
-import type { DocumentUpdate, DocumentUpdateOptions } from "./documentQuery";
+import type { DocumentQuery, DocumentUpdateInput, DocumentUpdateOptions } from "./documentQuery";
 import { type LoaderBuilder, type ModelCls, makeLoaderBuilder } from "./loaderInfo";
 import type { DocumentProjection } from "./types";
 
@@ -15,7 +15,7 @@ interface DefaultMdlStats<
   TDocument,
   TSchema,
   _Partial extends Partial<TSchema> = Partial<TSchema>,
-  _FilterQuery extends QueryOf<TSchema> = QueryOf<TSchema>,
+  _FilterQuery extends DocumentQuery<TSchema> = DocumentQuery<TSchema>,
   _Projection = DocumentProjection<TSchema>,
 > {
   pickOneAndWrite: (query: _FilterQuery, rawData: _Partial) => Promise<TDocument>;
@@ -47,10 +47,10 @@ export interface UpdateResult {
   modifiedCount: number;
   upsertedId?: string | null;
 }
-export interface BulkWriteOperation<Raw, _RawDoc = DocumentModel<Raw>, _RawQuery = QueryOf<_RawDoc>> {
+export interface BulkWriteOperation<Raw, _RawDoc = DocumentModel<Raw>, _RawQuery = DocumentQuery<_RawDoc>> {
   updateOne: {
     filter: _RawQuery;
-    update: DocumentUpdate;
+    update: DocumentUpdateInput<_RawDoc>;
     upsert?: boolean;
   };
 }
@@ -69,7 +69,7 @@ export type Mdl<
   Doc,
   Raw,
   _RawDoc = DocumentModel<Raw>,
-  _RawQuery = QueryOf<_RawDoc>,
+  _RawQuery extends DocumentQuery<_RawDoc> = DocumentQuery<_RawDoc>,
   _Projection extends DocumentProjection<Raw> = DocumentProjection<Raw>,
 > = DefaultMdlStats<Doc, _RawDoc, Partial<_RawDoc>, _RawQuery, _Projection> & {
   refName: string;
@@ -79,8 +79,12 @@ export type Mdl<
   findById(id: string | undefined, projection?: _Projection): Promise<Doc | null>;
   countDocuments(query: _RawQuery): Promise<number>;
   exists(query: _RawQuery): Promise<string | null>;
-  updateOne(query: _RawQuery, update: DocumentUpdate, options?: DocumentUpdateOptions): Promise<UpdateResult>;
-  updateMany(query: _RawQuery, update: DocumentUpdate): Promise<UpdateResult>;
+  updateOne(
+    query: _RawQuery,
+    update: DocumentUpdateInput<_RawDoc>,
+    options?: DocumentUpdateOptions,
+  ): Promise<UpdateResult>;
+  updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>): Promise<UpdateResult>;
   deleteMany(query: _RawQuery): Promise<UpdateResult>;
   bulkWrite(operations: BulkWriteOperation<Raw, _RawDoc, _RawQuery>[]): Promise<UpdateResult>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.3.11-rc.0",
+  "version": "2.3.11-rc.10",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -198,6 +198,7 @@
     "cordova-plugin-purchase": "^13.16.0",
     "croner": "^10.0.1",
     "daisyui": "5.5.23",
+    "firebase": "^12.13.0",
     "ioredis": "^5.10.1",
     "mermaid": "^11.15.0",
     "postgres": "^3.4.9",
@@ -288,6 +289,9 @@
     "daisyui": {
       "optional": true
     },
+    "firebase": {
+      "optional": true
+    },
     "ioredis": {
       "optional": true
     },

package/server/proxy/localeWebProxy.ts

@@ -49,7 +49,12 @@ export class LocaleWebProxy implements WebProxy {
       (locale) => !pathname.startsWith(`/${locale}/`) && pathname !== `/${locale}`,
     );
 
-    if (!isInternalProxyRequest(requestUrl) && !isWellKnownRequest(pathname) && pathnameIsMissingLocale) {
+    if (
+      !isInternalProxyRequest(requestUrl) &&
+      !isWellKnownRequest(pathname) &&
+      !isApiRequest(pathname) &&
+      pathnameIsMissingLocale
+    ) {
       return Response.redirect(
         new URL(`/${getLocale(request)}/${pathname.slice(1)}${targetUrl.search}`, getPublicRequestUrl(request)),
         307,
@@ -90,3 +95,7 @@ function isInternalProxyRequest(requestUrl: URL): boolean {
 function isWellKnownRequest(pathname: string): boolean {
   return pathname === "/.well-known" || pathname.startsWith("/.well-known/");
 }
+
+function isApiRequest(pathname: string): boolean {
+  return pathname === "/api" || pathname.startsWith("/api/");
+}

package/server/resolver/database.resolver.ts

@@ -9,6 +9,7 @@ import {
   type DataInputOf,
   DataLoader,
   DocumentSchema,
+  type DocumentUpdateInput,
   documentQueryHelper,
   type FindQueryOption,
   fillMissingFilterArgs,
@@ -219,12 +220,12 @@ export class DatabaseResolver {
           findOne: (query: QueryOf<any>) => createFindOneChain(query),
           findById: (id: string | undefined) => (id ? store.findOne({ id }) : Promise.resolve(null)),
           countDocuments: (query: QueryOf<any>) => store.count(query),
-          updateOne: (query: QueryOf<any>, update: Record<string, unknown>, options?: { upsert?: boolean }) =>
+          updateOne: (query: QueryOf<any>, update: DocumentUpdateInput, options?: { upsert?: boolean }) =>
             store.updateOneByQuery(query, update, options),
-          updateMany: (query: QueryOf<any>, update: Record<string, unknown>) => store.updateManyByQuery(query, update),
+          updateMany: (query: QueryOf<any>, update: DocumentUpdateInput) => store.updateManyByQuery(query, update),
           deleteMany: (query: QueryOf<any>) => store.deleteManyByQuery(query),
           bulkWrite: (
-            operations: { updateOne: { filter: QueryOf<any>; update: Record<string, unknown>; upsert?: boolean } }[],
+            operations: { updateOne: { filter: QueryOf<any>; update: DocumentUpdateInput; upsert?: boolean } }[],
           ) => store.bulkWrite(operations),
           listenPre: (type: SaveEventType, listener: (doc: any, type: CRUDEventType) => PromiseOrObject<void>) =>
             schema.pre(type, function (this: any, _next, crudType) {

package/server/resolver/signal.resolver.ts

@@ -158,6 +158,16 @@ export class SignalResolver {
     const serviceName = `${refName}Service`;
     const capitalizedRefName = capitalize(refName);
 
+    const assertSliceQuery = (query: unknown, key: string) => {
+      if (Array.isArray(query))
+        throw new Error(
+          `Slice "${refName}.${key}" exec returned an array instead of a query descriptor. ` +
+            `Return a query from the slice's service (e.g. this.${refName}Service.queryBy...(...)), ` +
+            `not an executed list (listBy.../findMany...), which resolves to an array.`,
+        );
+      return query;
+    };
+
     class SliceEndpoint extends sliceEndpoint(sliceCls.srv, (builder) => {
       const endpointObj: { [key: string]: EndpointInfo } = {};
       Object.entries(sliceMeta).forEach(([key, sliceInfo]) => {
@@ -179,7 +189,10 @@ export class SignalResolver {
             const limit = Number(requestArgs[argLength + 1] ?? 20);
             const sort = requestArgs[argLength + 2] ?? "latest";
             const internalArgs = requestArgs.slice(argLength + 3);
-            const query = await sliceInfo.execFn?.apply(this, [...args, ...internalArgs, documentQueryHelper]);
+            const query = assertSliceQuery(
+              await sliceInfo.execFn?.apply(this, [...args, ...internalArgs, documentQueryHelper]),
+              key,
+            );
             return (await this[serviceName].__list(query, {
               skip,
               limit,
@@ -196,7 +209,10 @@ export class SignalResolver {
           .exec(async function (this: any, ...requestArgs: any) {
             const args = requestArgs.slice(0, argLength);
             const internalArgs = requestArgs.slice(argLength);
-            const query = await sliceInfo.execFn?.apply(this, [...args, ...internalArgs, documentQueryHelper]);
+            const query = assertSliceQuery(
+              await sliceInfo.execFn?.apply(this, [...args, ...internalArgs, documentQueryHelper]),
+              key,
+            );
             return await this[serviceName].__insight(query);
           });
       });

package/server/routeTreeBuilder.ts

@@ -18,9 +18,12 @@ import {
   parseRouteModuleKey,
   routeSegmentToTreePath,
 } from "akanjs/common";
+import { createElement } from "react";
 import { validatePageConfig } from "../client/frameConfig";
 import { resolveHeadExport, resolveMetadataHead } from "./metadata";
 
+type RouteModuleKindWithOverrides = "page" | "layout" | "overrides";
+
 export type PagesContext = Record<string, () => Promise<RouteModule>>;
 
 export const defaultPageState: PageState = {
@@ -197,6 +200,14 @@ export class RouteTreeBuilder {
     const targetPath = pathSegments[pathSegments.length - 1];
     if (!targetPath) return;
 
+    if (parsed.kind === "overrides") {
+      targetRouteMap.set(targetPath, {
+        ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
+        renderOverrides: this.#makeOverridesRender(filePath, loader),
+      } as Route);
+      return;
+    }
+
     const routeRender = RouteTreeBuilder.#makeRouteRender(filePath, parsed.kind, loader);
     targetRouteMap.set(targetPath, {
       ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
@@ -224,8 +235,10 @@ export class RouteTreeBuilder {
     const pathSegments = [...parentPaths, ...(currentPathSegment ? [currentPathSegment] : [])];
     const currentRootLayout = isRoot && route.renderLayout ? route.renderLayout : null;
     const currentLayout = !isRoot && route.renderLayout ? route.renderLayout : null;
+
+    const currentOverrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
     const renderRootLayouts = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
-    const renderLayouts = [...parentLayouts, ...(currentLayout ? [currentLayout] : [])];
+    const renderLayouts = [...parentLayouts, ...currentOverrideRenders, ...(currentLayout ? [currentLayout] : [])];
     if (route.renderLayout) {
       this.#fallbackRoutes.push({
         path: routePath,
@@ -237,7 +250,10 @@ export class RouteTreeBuilder {
     const routeHead = RouteTreeBuilder.#composeHeadResolvers(route.renderLayout?.resolveHead, parentHead);
     const pageRenderRootLayouts =
       route.pageIncludesOwnLayout === false && currentRootLayout ? parentRootLayouts : renderRootLayouts;
-    const pageRenderLayouts = route.pageIncludesOwnLayout === false && currentLayout ? parentLayouts : renderLayouts;
+    const pageRenderLayouts =
+      route.pageIncludesOwnLayout === false && currentLayout
+        ? [...parentLayouts, ...currentOverrideRenders]
+        : renderLayouts;
     const pageHead = route.pageIncludesOwnLayout === false ? parentHead : routeHead;
     return [
       ...(route.renderPage
@@ -262,7 +278,7 @@ export class RouteTreeBuilder {
     ];
   }
 
-  static #makeLazyModule(key: string, kind: "page" | "layout", loader: () => Promise<RouteModule>) {
+  static #makeLazyModule(key: string, kind: RouteModuleKindWithOverrides, loader: () => Promise<RouteModule>) {
     let cached: RouteModule | null = null;
     let loaded = false;
     RouteTreeBuilder.#moduleCacheStats.moduleCount += 1;
@@ -285,7 +301,12 @@ export class RouteTreeBuilder {
     };
   }
 
-  static #validateRouteModuleExports(key: string, kind: "page" | "layout", mod: RouteModule) {
+  static #validateRouteModuleExports(key: string, kind: RouteModuleKindWithOverrides, mod: RouteModule) {
+    if (kind === "overrides") {
+      
+      if (!mod.default) throw new Error(`[route-convention] ${key} generated override wrapper has no default export`);
+      return;
+    }
     const parsed = parseRouteModuleKey(key);
     const allowed =
       kind === "page"
@@ -378,6 +399,18 @@ export class RouteTreeBuilder {
     return routeRender;
   }
 
+  #makeOverridesRender(key: string, loader: () => Promise<RouteModule>): RouteRender {
+    const loadModule = RouteTreeBuilder.#makeLazyModule(key, "overrides", loader);
+    return {
+      isAsync: true,
+      render: (async ({ children }: LayoutProps) => {
+        const mod = await loadModule();
+        if (!mod.default) throw new Error(`[route-convention] ${key} generated override wrapper has no default export`);
+        return createElement(mod.default as never, { children } as never);
+      }) as RouteRender["render"],
+    };
+  }
+
   static #composeHeadResolvers(...resolvers: (ResolveHead | undefined)[]): ResolveHead | undefined {
     const chain = resolvers.filter((resolver): resolver is ResolveHead => Boolean(resolver));
     if (chain.length === 0) return undefined;