@wishknish/knishio-client-ts 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "productName": "Knish.IO TypeScript SDK Client",
   "description": "TypeScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs with enhanced type safety.",
   "license": "GPL-3.0-or-later",

package/src/KnishIOClient.ts

@@ -136,7 +136,8 @@ import type {
   MetaType,
   MetaId,
   BatchId,
-  MetaFilter
+  MetaFilter,
+  RequestPolicy
 } from '@/types'
 
 /**
@@ -152,6 +153,10 @@ export default class KnishIOClient {
   private $__client!: GraphQLClient
   private $__serverSdkVersion: number = 3
   private $__logging: boolean = false
+  // Default urql request policy applied to reads when the caller doesn't pass
+  // one. null = urql's default (cache-first). Server/sync clients set this to
+  // 'network-only' so a long-lived client never serves a stale cached read.
+  private $__defaultRequestPolicy: RequestPolicy | null = null
   private $__authTokenObjects: Record<string, AuthToken | null> = {}
   private $__authToken: AuthToken | null = null
   private $__authInProcess: boolean = false
@@ -176,6 +181,7 @@ export default class KnishIOClient {
     socket?: { socketUri: string | null; appKey?: string } | null
     serverSdkVersion?: number
     logging?: boolean
+    defaultRequestPolicy?: RequestPolicy | null
   }) {
     // Phase 2 Enhancement: Use standardized configuration validation
     const standardValidationResult = ConfigValidator.validateClientConfig(config)
@@ -213,14 +219,19 @@ export default class KnishIOClient {
       serverSdkVersion = 3,
       logging = false
     } = validatedConfig
-    
+    // Read from the RAW config: defaultRequestPolicy is an optional add-on the
+    // strict schema now permits, but the validated/inferred shape may not carry
+    // it depending on the parser, so take it straight from the caller's config.
+    const defaultRequestPolicy = (config.defaultRequestPolicy ?? null) as RequestPolicy | null
+
     this.initialize({
       uri: uri as string | string[],
       cellSlug: cellSlug as string | null,
       socket: socket as { socketUri: string | null; appKey?: string } | null,
       client: client as GraphQLClient | null,
       serverSdkVersion,
-      logging
+      logging,
+      defaultRequestPolicy
     })
   }
 
@@ -233,7 +244,8 @@ export default class KnishIOClient {
     socket = null,
     client = null,
     serverSdkVersion = 3,
-    logging = false
+    logging = false,
+    defaultRequestPolicy = null
   }: {
     uri: string | string[]
     cellSlug?: string | null
@@ -241,6 +253,7 @@ export default class KnishIOClient {
     client?: GraphQLClient | null
     serverSdkVersion?: number
     logging?: boolean
+    defaultRequestPolicy?: RequestPolicy | null
   }): void {
     this.reset()
 
@@ -269,6 +282,9 @@ export default class KnishIOClient {
     })
 
     this.$__serverSdkVersion = serverSdkVersion
+    // Config (not session state) — set here, NOT cleared in reset(), mirroring
+    // serverSdkVersion. A re-initialize updates it.
+    this.$__defaultRequestPolicy = defaultRequestPolicy
   }
 
   /**
@@ -324,6 +340,22 @@ export default class KnishIOClient {
     return this.$__serverSdkVersion
   }
 
+  /**
+   * Gets the client's default urql request policy (null = urql default).
+   */
+  getDefaultRequestPolicy(): RequestPolicy | null {
+    return this.$__defaultRequestPolicy
+  }
+
+  /**
+   * Sets the default urql request policy applied to reads that don't specify
+   * one. Pass 'network-only' on a long-lived server/sync client so it never
+   * serves a stale cached read; null restores urql's default (cache-first).
+   */
+  setDefaultRequestPolicy(policy: RequestPolicy | null): void {
+    this.$__defaultRequestPolicy = policy
+  }
+
   /**
    * Reset common properties
    */
@@ -568,7 +600,11 @@ export default class KnishIOClient {
   /**
    * Executes a query or mutation
    */
-  async executeQuery(query: Query | Mutation, variables: Record<string, any> | null = null): Promise<Response | null> {
+  async executeQuery(
+    query: Query | Mutation,
+    variables: Record<string, any> | null = null,
+    context: Record<string, any> = {}
+  ): Promise<Response | null> {
     // Check and refresh authorization token if needed
     // Guard with $__authInProcess to prevent recursive auth refresh
     if (this.$__authToken && this.$__authToken.isExpired() && !this.$__authInProcess) {
@@ -581,6 +617,8 @@ export default class KnishIOClient {
     }
 
     if (query instanceof MutationProposeMolecule) {
+      // Molecule submissions are writes — never cached, so no request-policy
+      // context applies; MutationProposeMolecule.execute takes only variables.
       return await this.withMoleculeLock(async () => {
         const response = await query.execute({ variables: variables || {} })
         this.handlePositionDrift(response)
@@ -588,8 +626,18 @@ export default class KnishIOClient {
       })
     }
 
-    // Execute the query
-    return await query.execute({ variables: variables || {} })
+    // Execute the query/mutation, forwarding any urql context (e.g.
+    // requestPolicy) assembled by the caller (queryMeta) / createQueryContext().
+    // When the caller did NOT specify a request policy, fall back to this
+    // client's defaultRequestPolicy (e.g. a long-lived server/sync client set
+    // to 'network-only' so it never serves a stale read from the urql cache —
+    // removing the footgun of having to pass network-only on every call).
+    // Precedence: per-call context.requestPolicy > client default > a query's
+    // own createQueryContext() (e.g. ContinuId) > urql default.
+    const effectiveContext = (this.$__defaultRequestPolicy && !(context as Record<string, any>).requestPolicy)
+      ? { requestPolicy: this.$__defaultRequestPolicy, ...context }
+      : context
+    return await query.execute({ variables: variables || {}, context: effectiveContext })
   }
 
   /**
@@ -1038,7 +1086,8 @@ export default class KnishIOClient {
     throughMolecule = false,
     values = null,
     keys = null,
-    atomValues = null
+    atomValues = null,
+    requestPolicy = null
   }: {
     metaType: MetaType | string
     metaId?: MetaId | string | null
@@ -1055,6 +1104,12 @@ export default class KnishIOClient {
     values?: any[] | null
     keys?: string[] | null
     atomValues?: any[] | null
+    /**
+     * urql request policy for this read. Pass 'network-only' to bypass the
+     * client's in-memory cache (e.g. sync engines that must see the current
+     * ledger state). Default null = urql's default (cache-first).
+     */
+    requestPolicy?: 'cache-first' | 'cache-only' | 'network-only' | 'cache-and-network' | null
   }): Promise<Response> {
     this.log('info', `KnishIOClient::queryMeta() - Querying metaType: ${metaType}, metaId: ${metaId}...`)
 
@@ -1109,7 +1164,8 @@ export default class KnishIOClient {
       })
     }
 
-    return this.executeQuery(query, variables) as Promise<Response>
+    const context = requestPolicy ? { requestPolicy } : {}
+    return this.executeQuery(query, variables, context) as Promise<Response>
   }
 
   /**

package/src/libraries/GraphQLClient.ts

@@ -159,18 +159,21 @@ export default class GraphQLClient implements IGraphQLClient {
   async query<TResult = unknown>(
     request: GraphQLRequest
   ): Promise<GraphQLResponse<TResult>> {
-    const { query, variables } = request
-    const result = await this.$__client.query(query, variables || {}).toPromise()
+    const { query, variables, context } = request
+    // Forward the urql context (e.g. requestPolicy: 'network-only'). Without
+    // this 3rd arg urql ignores requestPolicy and defaults to cache-first,
+    // serving stale results from a long-lived client's in-memory cache.
+    const result = await this.$__client.query(query, variables || {}, context).toPromise()
     return this.formatResponse<TResult>(result)
   }
 
   async mutation<TResult = unknown>(
     request: GraphQLRequest
   ): Promise<GraphQLResponse<TResult>> {
-    const { query, variables } = request
+    const { query, variables, context } = request
     // Support both query and mutation properties for backward compatibility
     const mutationString = (request as any).mutation || query
-    const result = await this.$__client.mutation(mutationString, variables || {}).toPromise()
+    const result = await this.$__client.mutation(mutationString, variables || {}, context).toPromise()
     return this.formatResponse<TResult>(result)
   }
 

package/src/schemas/index.ts

@@ -191,7 +191,8 @@ export const KnishIOClientConfigSchema = z.object({
   client: z.unknown().optional(),
   socket: z.unknown().optional(),
   serverSdkVersion: z.number().int().min(1).optional(),
-  logging: z.boolean().optional()
+  logging: z.boolean().optional(),
+  defaultRequestPolicy: z.enum(['cache-first', 'cache-only', 'network-only', 'cache-and-network']).nullable().optional()
 }).strict()
 
 // =============================================================================

package/src/types/index.ts

@@ -371,10 +371,23 @@ export interface SignatureResult {
 // GRAPHQL OPERATION TYPES
 // =============================================================================
 
+/**
+ * urql request policy (mirrors @urql/core's RequestPolicy). Controls whether a
+ * read hits the client's in-memory cache. 'network-only' bypasses it entirely.
+ */
+export type RequestPolicy = 'cache-first' | 'cache-only' | 'network-only' | 'cache-and-network'
+
 export interface GraphQLRequest {
   query: string
   variables?: Record<string, unknown>
   operationName?: string | null
+  /**
+   * Per-operation urql context (e.g. `{ requestPolicy: 'network-only' }`).
+   * Built by Query.execute() from createQueryContext() + per-call context and
+   * MUST be forwarded to the urql client, or requestPolicy is silently ignored
+   * and urql falls back to its default cache-first policy.
+   */
+  context?: Record<string, unknown>
 }
 
 export interface GraphQLResponse<T = unknown> {

package/src/validation/schemas.ts

@@ -206,7 +206,11 @@ export const KnishIOClientConfigSchema = z.object({
   client: z.unknown().optional(),
   socket: z.unknown().optional(),
   serverSdkVersion: z.number().int().min(1).max(10).default(4),
-  logging: z.boolean().default(false)
+  logging: z.boolean().default(false),
+  // Optional default urql request policy for reads (server/sync clients pass
+  // 'network-only'). Permitted by the strict schema so the constructor option
+  // isn't rejected.
+  defaultRequestPolicy: z.enum(['cache-first', 'cache-only', 'network-only', 'cache-and-network']).nullable().optional()
 }).strict()
 
 // Environment configuration with validation