quickbase-js 0.1.0-beta.10

package/open-api/utils/sharedUtils.ts

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+
+import { OpenAPIV2 } from "openapi-types";
+import { join } from "path";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { Project, PropertySignature, ts } from "ts-morph"; // Import ts from ts-morph
+import { simplifyName } from "../../src/utils.ts";
+
+// (Existing interfaces remain unchanged)
+export interface PropertyDetail {
+  name: string;
+  type: string;
+  required: boolean;
+  jsdoc?: string;
+  properties?: PropertyDetail[];
+}
+
+export interface ParamDetail {
+  name: string;
+  type: string;
+  required: boolean;
+  properties: PropertyDetail[];
+  description?: string;
+}
+
+export interface JsDocOptions {
+  summary: string;
+  opId: string;
+  paramDetails: ParamDetail[];
+  returnType: string;
+  returnTypeDetails: PropertyDetail[];
+  docLink: string;
+}
+
+export function mapOpenApiTypeToTs(
+  openApiType: string | string[] | undefined
+): string {
+  const type = Array.isArray(openApiType)
+    ? openApiType[0]
+    : openApiType || "any";
+  switch (type.toLowerCase()) {
+    case "integer":
+    case "int":
+    case "number":
+      return "number";
+    case "string":
+      return "string";
+    case "boolean":
+      return "boolean";
+    default:
+      return "any";
+  }
+}
+
+export function mapRefToType(
+  schema: OpenAPIV2.SchemaObject | OpenAPIV2.ReferenceObject | undefined,
+  modelImports: Set<string>,
+  spec: OpenAPIV2.Document,
+  depth: number = 0,
+  availableModels: string[],
+  missingTypes: Set<string>
+): string {
+  if (!schema) return "any";
+  if ("$ref" in schema && schema.$ref) {
+    const refParts = schema.$ref.split("/");
+    const model = refParts[refParts.length - 1];
+    const pascalModel = model.charAt(0).toUpperCase() + model.slice(1);
+    if (availableModels.includes(pascalModel)) {
+      modelImports.add(pascalModel);
+      return pascalModel;
+    }
+    missingTypes.add(pascalModel);
+    console.warn(`Type ${pascalModel} not found, defaulting to 'any'`);
+    return "any";
+  }
+  if ("type" in schema) {
+    if (schema.type === "object" && schema.properties) {
+      const props = schema.properties;
+      const propTypes = Object.entries(props).map(([key, prop]) => {
+        const propSchema = prop as OpenAPIV2.SchemaObject;
+        const propType = mapRefToType(
+          propSchema,
+          modelImports,
+          spec,
+          depth + 1,
+          availableModels,
+          missingTypes
+        );
+        return `${key}${propSchema.required ? "" : "?"}: ${propType}`;
+      });
+      return `{ ${propTypes.join("; ")} }`;
+    }
+    if (schema.type === "array" && schema.items) {
+      const items = schema.items as
+        | OpenAPIV2.SchemaObject
+        | OpenAPIV2.ReferenceObject;
+      const itemType = mapRefToType(
+        items,
+        modelImports,
+        spec,
+        depth + 1,
+        availableModels,
+        missingTypes
+      );
+      return `${itemType}[]`;
+    }
+    return mapOpenApiTypeToTs(schema.type);
+  }
+  return "any";
+}
+
+export function parseInterfaceProperties(
+  modelName: string,
+  modelsDir: string,
+  availableModels?: string[],
+  depth: number = 0,
+  visited: Set<string> = new Set()
+): PropertyDetail[] {
+  if (availableModels && (depth > 10 || visited.has(modelName))) {
+    console.warn(
+      `Recursion limit reached or circular reference detected for ${modelName}`
+    );
+    return [];
+  }
+  if (availableModels) visited.add(modelName);
+
+  const project = new Project();
+  const filePath = join(modelsDir, `${modelName}.ts`);
+  if (!existsSync(filePath)) {
+    console.warn(`Model file ${filePath} not found for ${modelName}`);
+    return [];
+  }
+  const sourceFile = project.addSourceFileAtPath(filePath);
+
+  // Try to get the interface first
+  let interfaceDec = sourceFile.getInterface(modelName);
+  if (!interfaceDec) {
+    // If no interface, check for a type alias (e.g., array type)
+    const typeAlias = sourceFile.getTypeAlias(modelName);
+    if (typeAlias) {
+      const typeNode = typeAlias.getTypeNode();
+      if (typeNode && typeNode.getKindName() === "ArrayType") {
+        const elementType = typeNode.getFirstChildByKindOrThrow(
+          ts.SyntaxKind.TypeReference // Use ts.SyntaxKind from ts-morph
+        );
+        const innerType = elementType.getText(); // e.g., "GetFields200ResponseItemsInner"
+        if (availableModels?.includes(innerType)) {
+          console.log(
+            `Detected array type alias ${modelName}, parsing inner type ${innerType}`
+          );
+          // Recursively parse the inner interface
+          return parseInterfaceProperties(
+            innerType,
+            modelsDir,
+            availableModels,
+            depth + 1,
+            visited
+          );
+        } else {
+          console.warn(
+            `Inner type ${innerType} not found in available models for ${modelName}`
+          );
+          return [];
+        }
+      }
+    }
+    console.warn(
+      `Interface or supported type alias ${modelName} not found in ${filePath}`
+    );
+    return [];
+  }
+
+  // Parse properties of the interface
+  return interfaceDec.getProperties().map((prop: PropertySignature) => {
+    const jsDocs = prop.getJsDocs();
+    const jsdocText =
+      jsDocs.length > 0 ? jsDocs[0].getDescription().trim() : undefined;
+    const propType = prop.getType().getText(prop);
+    let properties: PropertyDetail[] | undefined = undefined;
+
+    if (availableModels) {
+      const arrayMatch = propType.match(/(.+)\[\]$/);
+      if (arrayMatch) {
+        const innerType = arrayMatch[1].trim();
+        if (availableModels.includes(innerType) && !innerType.includes("[]")) {
+          properties = parseInterfaceProperties(
+            innerType,
+            modelsDir,
+            availableModels,
+            depth + 1,
+            visited
+          );
+        }
+      }
+    }
+
+    return {
+      name: prop.getName(),
+      type: propType,
+      required: !prop.hasQuestionToken(),
+      jsdoc: jsdocText,
+      properties: properties && properties.length > 0 ? properties : undefined,
+    };
+  });
+}
+
+export interface OperationDoc {
+  name: string;
+  summary: string;
+  method: string;
+  path: string;
+  parameters: ParamDetail[];
+  returns: string;
+  returnTypeDetails: PropertyDetail[] | undefined;
+  docLink: string;
+}
+
+export function parseOpenApiOperations(
+  specFile: string,
+  modelsDir: string
+): {
+  operations: OperationDoc[];
+  modelImports: Set<string>;
+  missingTypes: Set<string>;
+} {
+  if (!existsSync(specFile)) {
+    throw new Error(
+      `Spec file ${specFile} not found. Run 'npm run fix-spec' first.`
+    );
+  }
+  const spec: OpenAPIV2.Document = JSON.parse(readFileSync(specFile, "utf8"));
+  const availableModels = readdirSync(modelsDir)
+    .filter((file) => file.endsWith(".ts") && !file.startsWith("index"))
+    .map((file) => file.replace(".ts", ""));
+  const modelImports = new Set<string>();
+  const missingTypes = new Set<string>();
+  const operations: OperationDoc[] = [];
+  for (const [path, methodsObj] of Object.entries(
+    spec.paths as OpenAPIV2.PathsObject
+  )) {
+    if (!methodsObj) continue;
+    for (const [method, operation] of Object.entries(
+      methodsObj as OpenAPIV2.PathItemObject
+    )) {
+      const op = operation as OpenAPIV2.OperationObject | undefined;
+      if (!op || !op.operationId) continue;
+      const opId = simplifyName(op.operationId);
+      console.log(`Processing operation ${opId} (${method} ${path})`);
+      const paramDetails = (op.parameters || [])
+        .filter(
+          (p) =>
+            !["QB-Realm-Hostname", "Authorization", "User-Agent"].includes(
+              (p as OpenAPIV2.ParameterObject).name || ""
+            )
+        )
+        .map((p) => {
+          const param = p as OpenAPIV2.ParameterObject;
+          let type = "any";
+          let properties: PropertyDetail[] | undefined = undefined;
+          if ("schema" in p && p.schema) {
+            type = mapRefToType(
+              p.schema,
+              modelImports,
+              spec,
+              1,
+              availableModels,
+              missingTypes
+            );
+            if ("$ref" in p.schema && p.schema.$ref) {
+              const refParts = p.schema.$ref.split("/");
+              const model = refParts[refParts.length - 1];
+              const pascalModel =
+                model.charAt(0).toUpperCase() + model.slice(1);
+              properties = parseInterfaceProperties(
+                pascalModel,
+                modelsDir,
+                availableModels
+              );
+            } else if (type !== "any" && availableModels.includes(type)) {
+              properties = parseInterfaceProperties(
+                type,
+                modelsDir,
+                availableModels
+              );
+            }
+          } else if ("type" in p) {
+            type = mapOpenApiTypeToTs(p.type);
+          }
+          return {
+            name: param.in === "body" ? "body" : param.name,
+            type,
+            required: param.required || false,
+            description: param.description || "",
+            properties: properties || [],
+          };
+        });
+      const returnTypes = ["200", "207"]
+        .map(
+          (code) => (op.responses?.[code] as OpenAPIV2.ResponseObject)?.schema
+        )
+        .filter(Boolean)
+        .map((schema) =>
+          mapRefToType(
+            schema!,
+            modelImports,
+            spec,
+            1,
+            availableModels,
+            missingTypes
+          )
+        );
+      const returnType =
+        returnTypes.length > 1
+          ? returnTypes.join(" | ")
+          : returnTypes[0] || "void";
+      const returnTypeDetailsRaw = returnTypes
+        .filter((type) => type !== "void" && availableModels.includes(type))
+        .map((type) =>
+          parseInterfaceProperties(type, modelsDir, availableModels)
+        )
+        .flat();
+      const returnTypeDetails =
+        returnTypeDetailsRaw.length > 0
+          ? returnTypeDetailsRaw.map((prop) => ({
+              ...prop,
+              properties:
+                prop.properties && prop.properties.length > 0
+                  ? [...prop.properties]
+                  : undefined,
+            }))
+          : undefined;
+      operations.push({
+        name: opId,
+        summary: op.summary || "No description.",
+        method: method.toUpperCase(),
+        path,
+        parameters: paramDetails,
+        returns: returnType,
+        returnTypeDetails,
+        docLink: `https://developer.quickbase.com/operation/${op.operationId}`,
+      });
+    }
+  }
+  return { operations, modelImports, missingTypes };
+}
+
+// New shared function
+export function getPropertyDescription(prop: PropertyDetail): string {
+  return prop.jsdoc
+    ? prop.jsdoc.replace(/@type\s*{[^}]+}\s*@memberof\s*\w+/, "").trim()
+    : `Type: ${prop.type}`;
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "quickbase-js",
+  "version": "0.1.0-beta.10",
+  "description": "QuickBase JavaScript client for frameworks and vanilla JS",
+  "type": "module",
+  "main": "dist/esm/quickbase.js",
+  "module": "dist/esm/quickbase.js",
+  "types": "dist/esm/quickbase.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/esm/quickbase.d.ts",
+      "import": {
+        "minified": "./dist/esm/quickbase.min.js",
+        "default": "./dist/esm/quickbase.js"
+      },
+      "require": {
+        "minified": "./dist/umd/quickbase.umd.min.js",
+        "default": "./dist/umd/quickbase.umd.js"
+      },
+      "umd:types": "./dist/umd/quickbase.umd.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:esm && npm run build:umd",
+    "build:esm": "rimraf dist/esm dist/temp dist/temp-src && node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' build-esm.js",
+    "build:umd": "rimraf dist/umd dist/temp dist/temp-src && node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' build-umd.js",
+    "release": "standard-version",
+    "release:beta": "standard-version --prerelease beta",
+    "release:alpha": "standard-version --prerelease alpha",
+    "release:push": "npm run release:beta && git push --follow-tags origin main",
+    "release:publish": "npm run release:push && npm publish --tag beta",
+    "release:stable": "standard-version && git push --follow-tags origin main && npm publish",
+    "gen:fixspec": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/fix-spec-main.ts",
+    "gen:openapi": "rimraf src/generated && node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/regenerate-client.ts",
+    "gen:openapi:post": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/post-process-generated.ts",
+    "gen:unified": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/generate-unified-interface.ts",
+    "gen:docsdata": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/generateDocsJson.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "gen:all": "npm run gen:fixspec && npm run gen:openapi && npm run gen:openapi:post && npm run gen:unified && npm run gen:docsdata && npm run docs:build",
+    "log-gen": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' tools/log-gen.ts",
+    "test:all": "vitest run tests/vitest/**/**/*.test.ts --reporter=basic && playwright test tests/playwright/qb --config playwright.config.ts --reporter=dot --quiet",
+    "test:pw:qb:all": "playwright test tests/playwright/qb --config playwright.config.ts",
+    "test:vitest:all": "vitest run tests/vitest/**/**/*.test.ts",
+    "test:vitest:qb": "vitest run tests/vitest/qb/**/*.test.ts",
+    "test:vitest:unit": "vitest run tests/vitest/unit/**/*.test.ts",
+    "test:vitest:qb:apps": "vitest run tests/vitest/qb/apps/*.test.ts",
+    "test:vitest:qb:auth": "vitest run tests/vitest/qb/auth/*.test.ts",
+    "test:vitest:qb:fields": "vitest run tests/vitest/qb/fields/*.test.ts",
+    "test:vitest:qb:records": "vitest run tests/vitest/qb/records/*.test.ts",
+    "test:vitest:qb:tables": "vitest run tests/vitest/qb/tables/*.test.ts",
+    "test:vitest:unit:apps": "vitest run tests/vitest/unit/apps/*.test.ts",
+    "test:vitest:unit:auth": "vitest run tests/vitest/unit/auth/*.test.ts",
+    "test:vitest:unit:fields": "vitest run tests/vitest/unit/fields/*.test.ts",
+    "test:vitest:unit:formulas": "vitest run tests/vitest/unit/formulas/*.test.ts",
+    "test:vitest:unit:records": "vitest run tests/vitest/unit/records/*.test.ts",
+    "test:vitest:unit:tables": "vitest run tests/vitest/unit/tables/*.test.ts",
+    "test:pw:qb:auth": "playwright test tests/playwright/qb/auth"
+  },
+  "devDependencies": {
+    "@openapitools/openapi-generator-cli": "^2.18.4",
+    "@playwright/test": "^1.51.0",
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/fast-json-patch": "^1.0.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.10",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "fast-json-patch": "^3.1.1",
+    "glob": "^10.4.5",
+    "js-yaml": "^4.1.0",
+    "jsdom": "^26.0.0",
+    "node-fetch": "^3.3.2",
+    "openapi-schema-validator": "^12.1.3",
+    "openapi-types": "^12.1.3",
+    "openapi-typescript": "^7.6.1",
+    "rimraf": "^5.0.10",
+    "rollup": "^4.35.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "standard-version": "^9.5.0",
+    "ts-morph": "^25.0.1",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.2",
+    "undici-types": "^7.5.0",
+    "vitepress": "^1.6.3",
+    "vitest": "^3.0.8"
+  }
+}

package/playwright.config.ts

@@ -0,0 +1,37 @@
+// playwright.config.ts
+import { defineConfig, devices } from "@playwright/test";
+
+const config = defineConfig({
+  fullyParallel: true,
+  workers: undefined, // Default: half of CPU cores (e.g., 2 on a 4-core machine)
+  // workers: 2, // Or explicitly set to 2 for controlled testing
+  testDir: "./tests/playwright",
+  timeout: 600000, // 10 minutes
+  retries: 2,
+  reporter: [
+    ["list"],
+    ["json", { outputFile: "test-artifacts/test-results.json" }],
+  ],
+  use: {
+    baseURL: "https://api.quickbase.com",
+    headless: true,
+    viewport: { width: 1280, height: 720 },
+    actionTimeout: 10000,
+    screenshot: "off",
+  },
+  outputDir: "test-artifacts",
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+});
+
+console.log(
+  `Loading Playwright: Testing temp token authorization in browser. Be patient, this could take at least 5min. Workers: ${
+    config.workers || "default (half CPU cores)"
+  }`
+);
+
+export default config;

package/rollup.config.js

@@ -0,0 +1,114 @@
+import terser from "@rollup/plugin-terser";
+import nodeResolve from "@rollup/plugin-node-resolve";
+import commonjs from "@rollup/plugin-commonjs";
+import dts from "rollup-plugin-dts";
+import typescript from "@rollup/plugin-typescript";
+
+const isProd = process.env.NODE_ENV === "production";
+
+// External dependencies for both ESM and UMD builds
+const external = [
+  "node:http",
+  "node:https",
+  "node:zlib",
+  "node:stream",
+  "node:buffer",
+  "node:util",
+  "node:url",
+  "node:net",
+  "node:fs",
+  "node:path",
+  "node-fetch",
+];
+
+// Global mappings for UMD (browser) build
+const globals = {
+  "node-fetch": "fetch", // Map node-fetch to window.fetch in browsers
+};
+
+export default [
+  // ESM Build
+  {
+    input: "src/quickbaseClient.ts",
+    output: {
+      dir: "dist/esm",
+      format: "esm",
+      sourcemap: true,
+      entryFileNames: "quickbase.js",
+    },
+    external,
+    plugins: [
+      nodeResolve({ preferBuiltins: true }), // Node.js resolution
+      commonjs(), // Convert CommonJS to ESM
+      typescript({
+        tsconfig: "./tsconfig.json",
+        noEmitOnError: true, // Fail on TypeScript errors
+        // Use Rollup to emit JavaScript, overriding noEmit for this build
+      }),
+      isProd && terser(), // Minification for production
+    ],
+  },
+  // UMD Build
+  {
+    input: "src/quickbaseClient.ts",
+    output: {
+      file: "dist/umd/quickbase.umd.js",
+      format: "umd",
+      name: "QuickbaseJS", // Global name for browser
+      sourcemap: true,
+      globals,
+    },
+    external,
+    plugins: [
+      nodeResolve({ preferBuiltins: true, browser: true }), // Browser-first resolution
+      commonjs(), // Convert CommonJS to UMD
+      typescript({
+        tsconfig: "./tsconfig.json",
+        noEmitOnError: true, // Fail on TypeScript errors
+        // Use Rollup to emit JavaScript, overriding noEmit for this build
+      }),
+      isProd && terser(), // Minification for production
+    ],
+  },
+  // ESM Declarations
+  {
+    input: "src/quickbaseClient.ts",
+    output: {
+      file: "dist/esm/quickbase.d.ts",
+      format: "esm",
+    },
+    plugins: [
+      dts({
+        tsconfig: "./tsconfig.json",
+        respectExternal: true, // Include external dependencies in declarations
+      }),
+    ],
+  },
+  // UMD Declarations
+  {
+    input: "src/quickbaseClient.ts",
+    output: {
+      file: "dist/umd/quickbase.umd.d.ts",
+      format: "umd",
+    },
+    plugins: [
+      dts({
+        tsconfig: "./tsconfig.json",
+        respectExternal: true, // Include external dependencies in declarations
+      }),
+    ],
+  },
+].map((config) => ({
+  ...config,
+  onwarn(warning, warn) {
+    // Suppress TypeScript plugin warnings
+    if (
+      warning.code === "PLUGIN_WARNING" &&
+      warning.plugin === "typescript" &&
+      warning.message.includes("TS5096")
+    ) {
+      return;
+    }
+    warn(warning);
+  },
+}));