prostgles-server 4.2.180 → 4.2.182

package/documentation/utils/generateClientDocs.ts

@@ -1,9 +1,8 @@
 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 { getObjectEntries, isDefined, TableHandler } from "prostgles-types";
 import { definitions } from "./clientTypes";
+import { getResolvedTypes } from "./getResolvedTypes";
 import { TS_Function, TS_Type } from "./getSerializableType";
 
 const testFolderPath = `${__dirname}/../../../tests/`;
@@ -14,8 +13,8 @@ export const generateClientDocs = () => {
     `${testFolderPath}/client/node_modules/prostgles-client/dist/prostgles.d.ts`
   );
   const excludedTypes = [
-    "FullFilter",
-    "FullFilter<T, S> | undefined",
+    // "FullFilter",
+    // "FullFilter<T, S> | undefined",
     "FieldFilter | undefined",
     "SyncOptions",
     "SyncOneOptions",
@@ -24,10 +23,7 @@ export const generateClientDocs = () => {
   const { resolvedTypes, visitedMaps } = getResolvedTypes({
     filePath: clientFilePath,
     filter: {
-      nodeNames: [
-        // "ViewHandlerClient",
-        "TableHandlerClient",
-      ],
+      nodeNames: ["TableHandlerClient"],
       excludedTypes,
     },
   });
@@ -57,8 +53,51 @@ export const generateClientDocs = () => {
     }
   );
 
-  const docPath = `${docsFolder}CLIENT.md`;
-  generateMDX(docPath);
+  const docPath = `${docsFolder}METHODS.md`;
+
+  const tableHandler = definitions[0];
+  const isomotphicMethodNames = {
+    count: 1,
+    delete: 1,
+    find: 1,
+    insert: 1,
+    update: 1,
+    findOne: 1,
+    getColumns: 1,
+    getInfo: 1,
+    size: 1,
+    subscribe: 1,
+    subscribeOne: 1,
+    updateBatch: 1,
+    upsert: 1,
+  } satisfies Record<keyof TableHandler, 1>;
+
+  const isomorphicMd = getMethodsDocs(
+    getObjectEntries(tableHandler.properties).filter(
+      ([methodName]) => isomotphicMethodNames[methodName]
+    )
+  );
+  const clientMd = getMethodsDocs(
+    getObjectEntries(tableHandler.properties).filter(
+      ([methodName]) => !isomotphicMethodNames[methodName]
+    )
+  );
+
+  const result = [
+    `# Isomorphic Methods`,
+    ``,
+    `The following methods are available on the client and server.`,
+    ``,
+    isomorphicMd.join("\n\n"),
+
+    `# Client Methods`,
+    ``,
+    `The following methods are available on the client.`,
+    ``,
+    clientMd.join("\n\n"),
+  ].join("\n");
+
+  fs.writeFileSync(docPath, result, { encoding: "utf-8" });
 };
 
 const getAliasWithoutGenerics = (type: TS_Type) => {
@@ -66,45 +105,65 @@ const getAliasWithoutGenerics = (type: TS_Type) => {
   return type.aliasSymbolescapedName || type.alias;
 };
 
-export const generateMDX = (filePath: string) => {
-  const tableHandler = definitions[0];
-  const mdxContent = getObjectEntries(tableHandler.properties).map(([methodName, _methodInfo]) => {
+const getMethodsDocs = (methods: [name: string, TS_Type][]) => {
+  return methods.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 "";
+    const args = `${methodInfo.arguments
+      .map((arg) => `${arg.name}${arg.optional ? "?" : ""}: ${getAliasWithoutGenerics(arg)}`)
+      .join(", ")}`;
+    const rType = `${methodInfo.returnType.aliasSymbolescapedName || methodInfo.returnType.alias}`
+      .replaceAll("<", "&lt;")
+      .replaceAll(">", "&gt;");
     return [
-      `## ${methodName}()`,
+      `## ${methodName}<span style="opacity: 0.6;">(${args}): ${rType}</span>`,
       methodInfo.comments ?? "",
-      `\`\`\`typescript
-  ${methodName}: (${methodInfo.arguments
-    .map((arg) => `${arg.name}${arg.optional ? "?" : ""}: ${getAliasWithoutGenerics(arg)}`)
-    .join(", ")}): ${methodInfo.returnType.aliasSymbolescapedName || methodInfo.returnType.alias}
-  \`\`\``,
-      `#### Arguments`,
+      `\`\`\`typescript`,
+      `${methodName}: (): `,
+      `\`\`\``,
+      `#### Parameters`,
       ``,
       ...methodInfo.arguments.map((arg) => {
         return renderType(arg, 2, { name: arg.name, optional: arg.optional });
       }),
-      `#### Return type`,
-      renderType(methodInfo.returnType, 0, undefined),
+      // `#### Return type`,
+      `#### ` + renderType(methodInfo.returnType, 0, undefined),
     ].join("\n");
   });
-  const result = mdxContent.join("\n\n");
-  fs.writeFileSync(filePath, result, { encoding: "utf-8" });
 };
 
+const renderedAliases = new Set<string>();
 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)}` : ""}`;
+  const typeAlias = `\`${type.aliasSymbolescapedName || type.alias}\``;
+  const typeText =
+    type.aliasSymbolescapedName && type.type === "object" ?
+      `<span style="color: green;">${type.aliasSymbolescapedName}</span>`
+    : typeAlias;
+  const title = [
+    `${indentText}${argOrProp?.name ? `- **${argOrProp.name}**: ` : ""}${typeAlias}`,
+    `${type.comments ? `${removeLineBreaks(type.comments, indentText + "  ")}` : ""}`,
+  ].join("\n\n");
+
+  if (typeAlias?.includes("FullFilter")) {
+    // debugger;
+  }
+  /**
+   * Re-use rendered types by linking them through an anchor tag
+   */
+  if (type.aliasSymbolescapedName && argOrProp?.name) {
+    renderedAliases.add(type.aliasSymbolescapedName);
+    console.log(type.aliasSymbolescapedName);
+  }
+
   if (type.type === "primitive" || type.type === "literal") {
     return title;
   }
@@ -133,10 +192,19 @@ const renderType = (
   return title;
 };
 
-const removeLineBreaks = (str = "") =>
+const removeLineBreaks = (str: string, indent: string) =>
   str
     .split("\n")
     .map((line) => {
-      if (!line.trim().endsWith(".")) return `${line}.`;
+      return `${indent}${line.trimStart()}`;
     })
-    .join(" ");
+    .join("\n");
+
+const renderTypeAlias = (type: TS_Type) => {
+  const typeAlias = type.aliasSymbolescapedName || type.alias;
+  const style = type.aliasSymbolescapedName ? `style="color: green;"` : "";
+  // if (renderedAliases.has(typeAlias)) {
+  //   return `<a ${style} href="#${typeAlias}">${typeAlias}</a>`;
+  // }
+  return `<span ${style}>${typeAlias}</span>`;
+};

package/documentation/utils/generateServerDocs.ts

@@ -15,7 +15,6 @@ export const generateServerDocs = () => {
   );
   const {
     resolvedTypes: [ProstglesInitOptions],
-    visitedMaps,
   } = getResolvedTypes({
     filePath: serverFilePath,
     filter: {
@@ -28,8 +27,15 @@ export const generateServerDocs = () => {
     },
   });
 
-  if (!ProstglesInitOptions) throw new Error("ProstglesInitOptions not found");
-  const prostglesInitOpts = definitions[0];
+  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" });
+
+  const prostglesInitOpts = (definitions as any)[0];
+  if (!ProstglesInitOptions || !prostglesInitOpts)
+    throw new Error("ProstglesInitOptions not found");
   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.`,
@@ -44,8 +50,8 @@ export const generateServerDocs = () => {
     `Basic example:`,
     `\`\`\`typescript`,
     `import prostgles from "prostgles-server";`,
-    `import { DBSchemaGenerated } from "./DBSchemaGenerated";`,
-    `prostgles<DBSchemaGenerated>({`,
+    `import { DBGeneratedSchema } from "./DBGeneratedSchema";`,
+    `prostgles<DBGeneratedSchema>({`,
     `  dbConnection: {`,
     `    host: "localhost",`,
     `    port: 5432,`,
@@ -66,6 +72,7 @@ export const generateServerDocs = () => {
     `\`\`\``,
     `### Configuration options`,
     ...getObjectEntries(prostglesInitOpts.properties).map(([propName, prop]) => {
+      //@ts-ignore
       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;
@@ -73,10 +80,5 @@ export const generateServerDocs = () => {
     }),
   ].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/getSerializableType.ts

@@ -4,8 +4,8 @@ import { AnyObject, isDefined } from "prostgles-types";
 type TS_Base = {
   alias?: string;
   aliasSymbolescapedName?: string;
-  intersectionParent?: string;
   comments?: string;
+  intersectionParent?: string;
 };
 
 export type TS_Literal = TS_Base & {
@@ -359,12 +359,22 @@ export const getSerializableType = (
         opts,
         depth + 1
       );
-      intersectionType.intersectionParent = aliasSymbolescapedName || alias;
+
+      if (intersectionType.type === "object") {
+        intersectionType.intersectionParent = aliasSymbolescapedName;
+      }
       return intersectionType;
     });
     if (intersectionTypes.every((t) => t.type === "object")) {
       const properties = (intersectionTypes as TS_Object[]).reduce((acc, t) => {
-        return { ...acc, ...t.properties };
+        const propertiesWithParentObject = Object.entries(t.properties).reduce(
+          (acc, [k, v]) => ({
+            ...acc,
+            [k]: { ...v, intersectionParent: t.aliasSymbolescapedName },
+          }),
+          {}
+        );
+        return { ...acc, ...propertiesWithParentObject };
       }, {});
       return withAlias({
         type: "object",

package/documentation/utils/loadTsFile.ts

@@ -2,10 +2,8 @@ import * as path from "path";
 import * as ts from "typescript";
 
 export const loadTsFile = (filePath: string) => {
-  // Normalize file path
   const absolutePath = path.resolve(filePath);
 
-  // Create compiler host and program
   const configPath = ts.findConfigFile(
     path.dirname(absolutePath),
     ts.sys.fileExists,
@@ -16,7 +14,6 @@ export const loadTsFile = (filePath: string) => {
     throw new Error("Could not find a valid 'tsconfig.json'.");
   }
 
-  // Parse the config file
   const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
   const parsedConfig = ts.parseJsonConfigFileContent(
     configFile.config,
@@ -24,7 +21,6 @@ export const loadTsFile = (filePath: string) => {
     path.dirname(configPath)
   );
 
-  // Create program
   const program = ts.createProgram({
     rootNames: [absolutePath],
     options: parsedConfig.options,

package/documentation/utils/serverTypes.ts

@@ -46,15 +46,10 @@ export const definitions = [
         "optional": false,
         "comments": "Called when the prostgles server is ready to accept connections.\nIt waits for auth, tableConfig and other async configurations to complete before executing"
       },
-      "dbOptions": {
-        "type": "reference",
-        "alias": "IDefaults",
-        "optional": true
-      },
       "tsGeneratedTypesDir": {
         "type": "reference",
         "alias": "string | undefined",
-        "comments": "If defined then a `DBSchemaGenerated.d.ts` file will be created in the provided directory.\nThis file exports a `DBSchemaGenerated` type which contains types for the database tables and\ncan be used as a generic type input for the prostgles instances to ensure type safety",
+        "comments": "If defined then a `DBGeneratedSchema.d.ts` file will be created in the provided directory.\nThis file exports a `DBGeneratedSchema` type which contains types for the database tables and\ncan be used as a generic type input for the prostgles instances to ensure type safety",
         "optional": true
       },
       "disableRealtime": {
@@ -295,7 +290,7 @@ export const definitions = [
           }
         ],
         "optional": true,
-        "comments": "If truthy then DBSchemaGenerated.d.ts will be updated\nand \"onReady\" will be called with new schema on both client and server"
+        "comments": "If truthy then DBGeneratedSchema.d.ts will be updated\nand \"onReady\" will be called with new schema on both client and server"
       },
       "keywords": {
         "type": "reference",
@@ -310,8 +305,7 @@ export const definitions = [
       },
       "fileTable": {
         "type": "reference",
-        "alias": "FileTableConfig",
-        "aliasSymbolescapedName": "FileTableConfig",
+        "alias": "FileTableConfig | undefined",
         "comments": "Enables file storage and serving.\nCurrently supports saving files locally or to AWS S3",
         "optional": true
       },

package/documentation/utils/tsconfig.json

@@ -2,12 +2,12 @@
   "files": ["generateDocs.ts"],
   "compilerOptions": {
     "baseUrl": ".",
-    "target": "es2019",
+    "target": "es2021",
     "lib": [
       "es6",
       "dom", 
       "es2017",
-      "es2019",
+      "es2021",
     ],
     "strict": true,
     "module": "commonjs",