prostgles-server 4.2.178 → 4.2.180

package/documentation/utils/generateClientDocs.ts

@@ -0,0 +1,142 @@
+import * as fs from "fs";
+import * as path from "path";
+import { isDefined } from "prostgles-types";
+import { getResolvedTypes } from "./getResolvedTypes";
+import { getObjectEntries } from "prostgles-types";
+import { definitions } from "./clientTypes";
+import { TS_Function, TS_Type } from "./getSerializableType";
+
+const testFolderPath = `${__dirname}/../../../tests/`;
+const docsFolder = `${__dirname}/../../`;
+
+export const generateClientDocs = () => {
+  const clientFilePath = path.resolve(
+    `${testFolderPath}/client/node_modules/prostgles-client/dist/prostgles.d.ts`
+  );
+  const excludedTypes = [
+    "FullFilter",
+    "FullFilter<T, S> | undefined",
+    "FieldFilter | undefined",
+    "SyncOptions",
+    "SyncOneOptions",
+    "PG_COLUMN_UDT_DATA_TYPE",
+  ];
+  const { resolvedTypes, visitedMaps } = getResolvedTypes({
+    filePath: clientFilePath,
+    filter: {
+      nodeNames: [
+        // "ViewHandlerClient",
+        "TableHandlerClient",
+      ],
+      excludedTypes,
+    },
+  });
+
+  const jsonTypes = JSON.stringify(
+    [
+      ...resolvedTypes,
+      ...visitedMaps
+        .flatMap((m) =>
+          Array.from(m.values()).map((v) =>
+            excludedTypes.includes(v.resolvedType.alias ?? "") ? v.resolvedType : undefined
+          )
+        )
+        .filter(isDefined),
+    ] satisfies TS_Type[],
+    null,
+    2
+  );
+  fs.writeFileSync(
+    `${__dirname}/../clientTypes.ts`,
+    [
+      `import type { TS_Type } from "./getSerializableType";`,
+      `export const definitions = ${jsonTypes} as const satisfies TS_Type[];`,
+    ].join("\n"),
+    {
+      encoding: "utf-8",
+    }
+  );
+
+  const docPath = `${docsFolder}CLIENT.md`;
+  generateMDX(docPath);
+};
+
+const getAliasWithoutGenerics = (type: TS_Type) => {
+  if (type.type === "union") return type.types.map(getAliasWithoutGenerics).join(" | ");
+  return type.aliasSymbolescapedName || type.alias;
+};
+
+export const generateMDX = (filePath: string) => {
+  const tableHandler = definitions[0];
+  const mdxContent = getObjectEntries(tableHandler.properties).map(([methodName, _methodInfo]) => {
+    const methodInfo = (
+      _methodInfo.type === "function" ?
+        (_methodInfo as TS_Function)
+        // : _methodInfo.type === "union" ? _methodInfo.types.find((t) => t.type === "function")
+      : undefined) as TS_Function | undefined;
+    if (!methodInfo) return "";
+    return [
+      `## ${methodName}()`,
+      methodInfo.comments ?? "",
+      `\`\`\`typescript
+  ${methodName}: (${methodInfo.arguments
+    .map((arg) => `${arg.name}${arg.optional ? "?" : ""}: ${getAliasWithoutGenerics(arg)}`)
+    .join(", ")}): ${methodInfo.returnType.aliasSymbolescapedName || methodInfo.returnType.alias}
+  \`\`\``,
+      `#### Arguments`,
+      ``,
+      ...methodInfo.arguments.map((arg) => {
+        return renderType(arg, 2, { name: arg.name, optional: arg.optional });
+      }),
+      `#### Return type`,
+      renderType(methodInfo.returnType, 0, undefined),
+    ].join("\n");
+  });
+  const result = mdxContent.join("\n\n");
+  fs.writeFileSync(filePath, result, { encoding: "utf-8" });
+};
+
+const renderType = (
+  type: TS_Type,
+  indent = 2,
+  argOrProp: { name: string; optional: boolean } | undefined
+): string => {
+  const indentText = " ".repeat(indent);
+  const title = `${indentText}${argOrProp?.name ? `- **${argOrProp.name}**: ` : ""}\`${
+    type.aliasSymbolescapedName || type.alias
+  }\`  ${type.comments ? ` - ${removeLineBreaks(type.comments)}` : ""}`;
+  if (type.type === "primitive" || type.type === "literal") {
+    return title;
+  }
+  if (type.type === "object") {
+    return (
+      title +
+      `\n` +
+      getObjectEntries(type.properties)
+        .map(([name, p]) => renderType(p, indent + 2, { name, optional: p.optional }))
+        .join("\n")
+    );
+  }
+
+  if (type.type === "promise") {
+    const innerType = renderType(type.innerType, indent, argOrProp);
+    // if (argOrProp?.name) {
+    //   return [title, innerType].join("\n");
+    // }
+    return innerType;
+  }
+
+  if (type.type === "array") {
+    return renderType(type.itemType, indent, argOrProp);
+  }
+
+  return title;
+};
+
+const removeLineBreaks = (str = "") =>
+  str
+    .split("\n")
+    .map((line) => {
+      if (!line.trim().endsWith(".")) return `${line}.`;
+    })
+    .join(" ");

package/documentation/utils/generateDocs.ts

@@ -0,0 +1,4 @@
+import { generateServerDocs } from "./generateServerDocs";
+import { generateClientDocs } from "./generateClientDocs";
+generateServerDocs();
+generateClientDocs();

package/documentation/utils/generateServerDocs.ts

@@ -0,0 +1,82 @@
+import * as fs from "fs";
+import * as path from "path";
+import { getResolvedTypes } from "./getResolvedTypes";
+import { definitions } from "./serverTypes";
+import { getObjectEntries } from "prostgles-types";
+import { TS_Type } from "./getSerializableType";
+
+const testFolderPath = `${__dirname}/../../../tests/`;
+const docsFolder = `${__dirname}/../../`;
+
+export const generateServerDocs = () => {
+  const serverFilePath = path.resolve(
+    // `${testFolderPath}/server/node_modules/prostgles-server/dist/DBSchemaBuilder.d.ts` // "DBOFullyTyped",
+    `${testFolderPath}/server/node_modules/prostgles-server/dist/ProstglesTypes.d.ts` // "ProstglesInitOptions",
+  );
+  const {
+    resolvedTypes: [ProstglesInitOptions],
+    visitedMaps,
+  } = getResolvedTypes({
+    filePath: serverFilePath,
+    filter: {
+      nodeNames: [
+        "ProstglesInitOptions",
+        // "DBOFullyTyped",
+      ],
+      excludedTypes: [],
+      maxDepth: 2,
+    },
+  });
+
+  if (!ProstglesInitOptions) throw new Error("ProstglesInitOptions not found");
+  const prostglesInitOpts = definitions[0];
+  const docs = [
+    `# Overview`,
+    `Our Isomorphic Typescript API allows connecting to a PostgreSQL database to get a realtime view of the data and schema. Interact with the data with full end-to-end type safety.`,
+    `### Installation`,
+    `To install the package, run:`,
+    `\`\`\`bash`,
+    `npm install prostgles-server`,
+    `\`\`\``,
+    `### Configuration`,
+    `To get started, you need to provide a configuration object to the server.`,
+    ``,
+    `Basic example:`,
+    `\`\`\`typescript`,
+    `import prostgles from "prostgles-server";`,
+    `import { DBSchemaGenerated } from "./DBSchemaGenerated";`,
+    `prostgles<DBSchemaGenerated>({`,
+    `  dbConnection: {`,
+    `    host: "localhost",`,
+    `    port: 5432,`,
+    `    database: "postgres"`,
+    `    user: process.env.PRGL_USER,`,
+    `    password: process.env.PRGL_PWD`,
+    `  },`,
+    `  tsGeneratedTypesDir: __dirname,`,
+    `  onReady: async ({ dbo }) => {`,
+    `    try {`,
+    `      await dbo.items.insert({ name: "a" });`,
+    `      console.log(await dbo.items.find());`,
+    `    } catch(err) {`,
+    `      console.error(err)`,
+    `    }`,
+    `  },`,
+    `});`,
+    `\`\`\``,
+    `### Configuration options`,
+    ...getObjectEntries(prostglesInitOpts.properties).map(([propName, prop]) => {
+      const title = `  - <strong>${propName}</strong> \`${(prop as TS_Type).aliasSymbolescapedName || (prop as TS_Type).alias}\``;
+      const comments = (prop as TS_Type).comments || "";
+      if (!comments) return title;
+      return [title, `  ` + comments + "  "].join("\n");
+    }),
+  ].join("\n");
+
+  const serverTypesStr = [
+    `import type { TS_Type } from "./getSerializableType";`,
+    `export const definitions = ${JSON.stringify([ProstglesInitOptions], null, 2)} as const satisfies TS_Type[];`,
+  ].join("\n");
+  fs.writeFileSync(`${docsFolder}/utils/serverTypes.ts`, serverTypesStr, { encoding: "utf-8" });
+  fs.writeFileSync(`${docsFolder}SERVER.md`, docs, { encoding: "utf-8" });
+};

package/documentation/utils/getResolvedTypes.ts

@@ -0,0 +1,45 @@
+import * as ts from "typescript";
+import { getSerializableType, TS_Type, VisitedTypesMap } from "./getSerializableType";
+import { loadTsFile } from "./loadTsFile";
+
+type Args = {
+  filePath: string;
+  filter?: {
+    nodeNames: string[];
+    excludedTypes: string[];
+    maxDepth?: number;
+  };
+};
+export const getResolvedTypes = ({ filePath, filter }: Args) => {
+  const { checker, sourceFile } = loadTsFile(filePath);
+
+  const results: TS_Type[] = [];
+  const visitedMaps: VisitedTypesMap[] = [];
+
+  const visit = (node: ts.Node) => {
+    // const nodeText = node.getText();
+    // if (nodeText.includes("DBOFullyTyped")) {
+    //   console.log("node.name.text", node.getText());
+    // }
+    if (ts.isTypeAliasDeclaration(node)) {
+      if (!filter || filter?.nodeNames.includes(node.name.text)) {
+        const type1 = checker.getTypeAtLocation(node.type);
+        const { resolvedType, visited } = getSerializableType(
+          type1,
+          checker,
+          undefined,
+          [],
+          filter,
+          0
+        );
+        results.push(resolvedType);
+        visitedMaps.push(visited);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return { resolvedTypes: results, visitedMaps };
+};