@zenstackhq/client-helpers 3.1.0 → 3.2.0

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@zenstackhq/client-helpers",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Helpers for implementing clients that consume ZenStack's CRUD service",
   "type": "module",
   "author": "ZenStack Team",
   "license": "MIT",
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -18,16 +21,16 @@
   "dependencies": {
     "decimal.js": "^10.4.3",
     "superjson": "^2.2.3",
-    "@zenstackhq/common-helpers": "3.1.0",
-    "@zenstackhq/schema": "3.1.0"
+    "@zenstackhq/schema": "3.2.0",
+    "@zenstackhq/common-helpers": "3.2.0"
   },
   "devDependencies": {
-    "@zenstackhq/eslint-config": "3.1.0",
-    "@zenstackhq/language": "3.1.0",
-    "@zenstackhq/sdk": "3.1.0",
-    "@zenstackhq/orm": "3.1.0",
-    "@zenstackhq/typescript-config": "3.1.0",
-    "@zenstackhq/vitest-config": "3.1.0"
+    "@zenstackhq/eslint-config": "3.2.0",
+    "@zenstackhq/language": "3.2.0",
+    "@zenstackhq/orm": "3.2.0",
+    "@zenstackhq/sdk": "3.2.0",
+    "@zenstackhq/vitest-config": "3.2.0",
+    "@zenstackhq/typescript-config": "3.2.0"
   },
   "scripts": {
     "build": "tsc --noEmit && tsup-node && pnpm test:typecheck",

package/.turbo/turbo-build.log

@@ -1,24 +0,0 @@
-
-> @zenstackhq/client-helpers@3.1.0 build /home/runner/work/zenstack-v3/zenstack-v3/packages/clients/client-helpers
-> tsc --noEmit && tsup-node && pnpm test:typecheck
-
-CLI Building entry: {"index":"src/index.ts","fetch":"src/fetch.ts"}
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.0
-CLI Using tsup config: /home/runner/work/zenstack-v3/zenstack-v3/packages/clients/client-helpers/tsup.config.ts
-CLI Target: esnext
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.js     25.68 KB
-ESM dist/fetch.js     2.73 KB
-ESM dist/index.js.map 63.32 KB
-ESM dist/fetch.js.map 5.94 KB
-ESM ⚡️ Build success in 136ms
-DTS Build start
-DTS ⚡️ Build success in 5075ms
-DTS dist/index.d.ts 10.28 KB
-DTS dist/fetch.d.ts 1.24 KB
-
-> @zenstackhq/client-helpers@3.1.0 test:typecheck /home/runner/work/zenstack-v3/zenstack-v3/packages/clients/client-helpers
-> tsc --noEmit --project tsconfig.test.json
-

package/eslint.config.js

@@ -1,4 +0,0 @@
-import config from '@zenstackhq/eslint-config/base.js';
-
-/** @type {import("eslint").Linter.Config} */
-export default config;

package/src/constants.ts

@@ -1,4 +0,0 @@
-/**
- * The default query endpoint.
- */
-export const DEFAULT_QUERY_ENDPOINT = '/api/model';

package/src/fetch.ts

@@ -1,107 +0,0 @@
-import { lowerCaseFirst } from '@zenstackhq/common-helpers';
-import Decimal from 'decimal.js';
-import SuperJSON from 'superjson';
-import type { QueryError } from './types';
-
-/**
- * Function signature for `fetch`.
- */
-export type FetchFn = (url: string, options?: RequestInit) => Promise<Response>;
-
-/**
- * A fetcher function that uses fetch API to make HTTP requests and automatically unmarshals
- * the response using superjson.
- */
-export async function fetcher<R>(url: string, options?: RequestInit, customFetch?: FetchFn): Promise<R> {
-    const _fetch = customFetch ?? fetch;
-    const res = await _fetch(url, options);
-    if (!res.ok) {
-        const errData = unmarshal(await res.text());
-        if (errData.error?.rejectedByPolicy && errData.error?.rejectReason === 'cannot-read-back') {
-            // policy doesn't allow mutation result to be read back, just return undefined
-            return undefined as any;
-        }
-        const error: QueryError = new Error('An error occurred while fetching the data.');
-        error.info = errData.error;
-        error.status = res.status;
-        throw error;
-    }
-
-    const textResult = await res.text();
-    try {
-        return unmarshal(textResult).data as R;
-    } catch (err) {
-        console.error(`Unable to deserialize data:`, textResult);
-        throw err;
-    }
-}
-
-/**
- * Makes a URL for the given endpoint, model, operation, and args that matches the RPC-style server API.
- */
-export function makeUrl(endpoint: string, model: string, operation: string, args?: unknown) {
-    const baseUrl = `${endpoint}/${lowerCaseFirst(model)}/${operation}`;
-    if (!args) {
-        return baseUrl;
-    }
-
-    const { data, meta } = serialize(args);
-    let result = `${baseUrl}?q=${encodeURIComponent(JSON.stringify(data))}`;
-    if (meta) {
-        result += `&meta=${encodeURIComponent(JSON.stringify({ serialization: meta }))}`;
-    }
-    return result;
-}
-
-SuperJSON.registerCustom<Decimal, string>(
-    {
-        isApplicable: (v): v is Decimal =>
-            v instanceof Decimal ||
-            // interop with decimal.js
-            v?.toStringTag === '[object Decimal]',
-        serialize: (v) => v.toJSON(),
-        deserialize: (v) => new Decimal(v),
-    },
-    'Decimal',
-);
-
-/**
- * Serialize the given value with superjson
- */
-export function serialize(value: unknown): { data: unknown; meta: unknown } {
-    const { json, meta } = SuperJSON.serialize(value);
-    return { data: json, meta };
-}
-
-/**
- * Deserialize the given value with superjson using the given metadata
- */
-export function deserialize(value: unknown, meta: any): unknown {
-    return SuperJSON.deserialize({ json: value as any, meta });
-}
-
-/**
- * Marshal the given value to a string using superjson
- */
-export function marshal(value: unknown) {
-    const { data, meta } = serialize(value);
-    if (meta) {
-        return JSON.stringify({ ...(data as any), meta: { serialization: meta } });
-    } else {
-        return JSON.stringify(data);
-    }
-}
-
-/**
- * Unmarshal the given string value using superjson, assuming the value is a JSON stringified
- * object containing the serialized data and serialization metadata.
- */
-export function unmarshal(value: string) {
-    const parsed = JSON.parse(value);
-    if (typeof parsed === 'object' && parsed?.data && parsed?.meta?.serialization) {
-        const deserializedData = deserialize(parsed.data, parsed.meta.serialization);
-        return { ...parsed, data: deserializedData };
-    } else {
-        return parsed;
-    }
-}

package/src/index.ts

@@ -1,9 +0,0 @@
-export * from './constants';
-export * from './invalidation';
-export * from './logging';
-export * from './mutator';
-export * from './nested-read-visitor';
-export * from './nested-write-visitor';
-export * from './optimistic';
-export * from './query-analysis';
-export * from './types';

package/src/invalidation.ts

@@ -1,89 +0,0 @@
-import type { SchemaDef } from '@zenstackhq/schema';
-import { log, type Logger } from './logging';
-import { getMutatedModels, getReadModels } from './query-analysis';
-import type { MaybePromise, ORMWriteActionType } from './types';
-
-/**
- * Type for a predicate that determines whether a query should be invalidated.
- */
-export type InvalidationPredicate = ({ model, args }: { model: string; args: unknown }) => boolean;
-
-/**
- * Type for a function that invalidates queries matching the given predicate.
- */
-export type InvalidateFunc = (predicate: InvalidationPredicate) => MaybePromise<void>;
-
-/**
- * Create a function that invalidates queries affected by the given mutation operation.
- *
- * @param model Model under mutation.
- * @param operation Mutation operation (e.g, `update`).
- * @param schema The schema.
- * @param invalidator Function to invalidate queries matching a predicate. It should internally
- * enumerate all query cache entries and invalidate those for which the predicate returns true.
- * @param logging Logging option.
- */
-export function createInvalidator(
-    model: string,
-    operation: string,
-    schema: SchemaDef,
-    invalidator: InvalidateFunc,
-    logging: Logger | undefined,
-) {
-    return async (...args: unknown[]) => {
-        const [_, variables] = args;
-        const predicate = await getInvalidationPredicate(
-            model,
-            operation as ORMWriteActionType,
-            variables,
-            schema,
-            logging,
-        );
-        await invalidator(predicate);
-    };
-}
-
-// gets a predicate for evaluating whether a query should be invalidated
-async function getInvalidationPredicate(
-    model: string,
-    operation: ORMWriteActionType,
-    mutationArgs: any,
-    schema: SchemaDef,
-    logging: Logger | undefined,
-): Promise<InvalidationPredicate> {
-    const mutatedModels = await getMutatedModels(model, operation, mutationArgs, schema);
-
-    return ({ model, args }) => {
-        if (mutatedModels.includes(model)) {
-            // direct match
-            if (logging) {
-                log(
-                    logging,
-                    `Marking "${model}" query for invalidation due to mutation "${operation}", query args: ${JSON.stringify(args)}`,
-                );
-            }
-            return true;
-        }
-
-        if (args) {
-            // traverse query args to find nested reads that match the model under mutation
-            if (findNestedRead(model, mutatedModels, schema, args)) {
-                if (logging) {
-                    log(
-                        logging,
-                        `Marking "${model}" query for invalidation due to mutation "${operation}", query args: ${JSON.stringify(args)}`,
-                    );
-                }
-                return true;
-            }
-        }
-
-        return false;
-    };
-}
-
-// find nested reads that match the given models
-function findNestedRead(visitingModel: string, targetModels: string[], schema: SchemaDef, args: any) {
-    const modelsRead = getReadModels(visitingModel, schema, args);
-    return targetModels.some((m) => modelsRead.includes(m));
-}

package/src/logging.ts

@@ -1,15 +0,0 @@
-/**
- * Logger configuration. `true` enables console logging. A function can be provided for custom logging.
- */
-export type Logger = boolean | ((message: string) => void);
-
-/**
- * Logs a message using the provided logger.
- */
-export function log(logger: Logger, message: string) {
-    if (typeof logger === 'function') {
-        logger(message);
-    } else if (logger) {
-        console.log(message);
-    }
-}