talizen 0.2.9 → 0.2.10

package/README.md

@@ -160,6 +160,24 @@ const result = await invoke<{ ok: boolean; id: string }>("booking.create", {
 await invoke("booking", { email: "hi@talizen.com" });
 ```
 
+### Server-side page context
+
+In `getServerSideProps`, use the injected server context for request metadata
+and cookies. Do not import `talizen/auth` or `talizen/func`, and do not read
+auth state or call Func from server-side page code:
+
+```ts
+import type { TalizenServerSideContext } from "talizen/server-runtime";
+
+export async function getServerSideProps(ctx: TalizenServerSideContext) {
+  return { props: { path: ctx.request.path } };
+}
+```
+
+Server-side context supports `ctx.request` and `ctx.cookies`. It intentionally
+does not expose `ctx.auth`, `ctx.db`, `ctx.cache`, or `ctx.func`; put login UI,
+private business data access, and writes in browser-side SDK/Func/API flows.
+
 ### Write function runtime code
 
 Func code can use TypeScript and import Func authoring types from `talizen/func-runtime`.
@@ -180,6 +198,22 @@ export function create(input: { title: string }, ctx: TalizenFuncContext) {
 }
 ```
 
+`ctx.db.query(table, query)` returns `{ total, list }`, where `total` is the
+matched record count before pagination and `list` is the current page:
+
+```ts
+import type { TalizenFuncContext } from "talizen/func-runtime";
+
+export function list(input: { offset?: number }, ctx: TalizenFuncContext) {
+  const result = ctx.db.query<{ title: string; status: string }>("book", {
+    where: { status: "published" },
+    limit: 20,
+    offset: input.offset || 0,
+  });
+  return { total: result.total, books: result.list };
+}
+```
+
 `ctx.db`, `ctx.cache`, `ctx.auth`, `ctx.request`, and `ctx.cookies` are injected by the Talizen Func runtime. `talizen/func-runtime` is a type-only authoring module; do not import runtime values from it.
 
 ## Package Layout
@@ -190,6 +224,7 @@ export function create(input: { title: string }, ctx: TalizenFuncContext) {
 - `talizen/form`: form submission helpers and related types.
 - `talizen/func`: custom function invocation helpers such as `invoke`.
 - `talizen/func-runtime`: Func-runtime-only `ctx` capability types.
+- `talizen/server-runtime`: getServerSideProps-only `ctx` capability types.
 
 ## Publish
 

package/func-runtime.d.ts

@@ -22,9 +22,13 @@ export interface DbQuery {
 export type DbRecord<T extends Record<string, unknown> = Record<string, unknown>> = T & {
     id: string;
 };
+export interface DbQueryResult<T extends Record<string, unknown> = Record<string, unknown>> {
+    total: number;
+    list: Array<DbRecord<T>>;
+}
 export interface FuncDbRuntime {
     get<T extends Record<string, unknown> = Record<string, unknown>>(table: string, id: string): DbRecord<T> | null;
-    query<T extends Record<string, unknown> = Record<string, unknown>>(table: string, query?: DbQuery): Array<DbRecord<T>>;
+    query<T extends Record<string, unknown> = Record<string, unknown>>(table: string, query?: DbQuery): DbQueryResult<T>;
     insert<T extends Record<string, unknown> = Record<string, unknown>>(table: string, data: T): DbRecord<T>;
     update<T extends Record<string, unknown> = Record<string, unknown>>(table: string, id: string, data: Partial<T>): {
         ok?: boolean;

package/index.d.ts

@@ -4,6 +4,7 @@ export * from "./cms.js";
 export * from "./captcha-ui.js";
 export * from "./form.js";
 export * from "./i18n.js";
+export * from "./server-runtime.js";
 type OneOrMany<T> = T | Array<T>;
 export interface MetadataTitle {
     default?: string;

package/index.js

@@ -4,3 +4,4 @@ export * from "./cms.js";
 export * from "./captcha-ui.js";
 export * from "./form.js";
 export * from "./i18n.js";
+export * from "./server-runtime.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talizen",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Talizen frontend SDK types for cms, form and core.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,10 @@
       "types": "./func-runtime.d.ts",
       "import": "./func-runtime.js"
     },
+    "./server-runtime": {
+      "types": "./server-runtime.d.ts",
+      "import": "./server-runtime.js"
+    },
     "./i18n": {
       "types": "./i18n.d.ts",
       "import": "./i18n.js"

package/server-runtime.d.ts

@@ -0,0 +1,40 @@
+export interface ServerReadonlyStringMap {
+    get(name: string): string | null;
+}
+export interface TalizenServerRequestRuntime {
+    host: string;
+    ip: string;
+    method: string;
+    path: string;
+    url: string;
+    headers: ServerReadonlyStringMap;
+    cookies: ServerReadonlyStringMap;
+}
+export interface ServerCookieSetOptions {
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: "lax" | "strict" | "none";
+}
+export interface TalizenServerCookieRuntime {
+    get(name: string): string | null;
+    set(name: string, value: string, options?: ServerCookieSetOptions): {
+        ok?: boolean;
+    };
+    delete(name: string, options?: Pick<ServerCookieSetOptions, "path" | "domain">): {
+        ok?: boolean;
+    };
+}
+export interface TalizenServerSideContext {
+    query: Record<string, string | string[]>;
+    searchParams: Record<string, string | string[]>;
+    params: Record<string, string>;
+    locale?: string;
+    locales?: string[];
+    defaultLocale?: string;
+    request: TalizenServerRequestRuntime;
+    req: TalizenServerRequestRuntime;
+    cookies: TalizenServerCookieRuntime;
+}

package/server-runtime.js

@@ -0,0 +1 @@
+export {};