From fd26d86a7888e3df3b232c1c9ad5a96015bf7fe4 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Fri, 4 Oct 2024 11:36:27 -0400 Subject: [PATCH 1/3] Fixed spacing between headers --- examples/mod.ts | 2 +- examples/use-message.ts | 2 +- websocket/websocket.ts | 5 +- www/components/api.tsx | 176 ++++++++++++++++++++++++++++++-------- www/components/tokens.tsx | 4 +- 5 files changed, 146 insertions(+), 43 deletions(-) diff --git a/examples/mod.ts b/examples/mod.ts index f2b8df1..298b7d8 100644 --- a/examples/mod.ts +++ b/examples/mod.ts @@ -1 +1 @@ -export { type Message, useMessages } from "./use-message.ts"; +export * from "./use-message.ts"; diff --git a/examples/use-message.ts b/examples/use-message.ts index 33e2570..72fc541 100644 --- a/examples/use-message.ts +++ b/examples/use-message.ts @@ -26,4 +26,4 @@ export interface Message { */ export function* useMessages(text?: string): Operation { return [{ text, code: undefined }]; -} +} \ No newline at end of file diff --git a/websocket/websocket.ts b/websocket/websocket.ts index 9c6d4ce..40cc99d 100644 --- a/websocket/websocket.ts +++ b/websocket/websocket.ts @@ -48,13 +48,12 @@ export interface WebSocketResource * console.log('event data: ', event.data); * yield* each.next(); * } - * * ``` * * @param url - The URL of the target WebSocket server to connect to. The URL must use one of the following schemes: ws, wss, http, or https, and cannot include a URL fragment. If a relative URL is provided, it is relative to the base URL of the calling script. For more detail, see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#url * * @param prototol - A single string or an array of strings representing the sub-protocol(s) that the client would like to use, in order of preference. If it is omitted, an empty array is used by default, i.e. []. For more details, see - + * * @returns an operation yielding a {@link WebSocketResource} */ export function useWebSocket( @@ -66,7 +65,7 @@ export function useWebSocket( * Create a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) * resource, but delegate the creation of the underlying websocket to a function * of your choice. This is necessary on platforms that do not have a global - * `WebSocket` constructor such as NodeJS <= 20. + * `WebSocket` constructor such as NodeJS \<= 20. * * The resource will not be returned until a connection has been * succesffuly established with the server and the diff --git a/www/components/api.tsx b/www/components/api.tsx index c734036..5185ae9 100644 --- a/www/components/api.tsx +++ b/www/components/api.tsx @@ -5,6 +5,7 @@ import type { InterfaceDef, ParamDef, TsTypeDef, + TsTypeParamDef, TsTypeRefDef, VariableDef, } from "https://deno.land/x/deno_doc@0.125.0/types.d.ts"; @@ -31,10 +32,14 @@ export function* API({ pkg }: DescriptionProps): Operation { elements.push( ( -
- {yield* Type({ node })} - -
+
+
+ {yield* Type({ node })} +
+
+ +
+
), ); } @@ -50,18 +55,12 @@ function* Type({ node }: TypeProps): Operation { switch (node.kind) { case "function": return ( -

+

{node.kind}{" "} {node.name} ( - <> - {node.functionDef.params.map((param) => ( - - ))} - + ): {node.functionDef.returnType ? : <>} @@ -71,10 +70,32 @@ function* Type({ node }: TypeProps): Operation { case "interface": return ( <> -

+ {/** TODO(taras): figure out why text-nowrap is missing **/} +

{node.kind} {node.name} + {node.interfaceDef.typeParams.length > 0 + ? ( + + ) + : <>} + {node.interfaceDef.extends + ? ( + <> + {" extends "} + <> + {node.interfaceDef.extends.flatMap( + (typeDef) => [, ", "], + ).slice(0, -1)} + + + ) + : <>}

- {" {"} + + {" {"} + {yield* TSInterfaceDef({ interfaceDef: node.interfaceDef })} {"}"} @@ -111,17 +132,21 @@ function* TSInterfaceDef( ): Operation { const elements: JSXElement[] = []; for (const property of interfaceDef.properties) { + const jsDoc = yield* call(function* (): Operation { + if (property.jsDoc?.doc) { + const mod = yield* useMDX(property.jsDoc?.doc); + return mod.default(); + } + }); elements.push( -
  • -
    - {yield* call(function* (): Operation { - if (property.jsDoc?.doc) { - const mod = yield* useMDX(property.jsDoc?.doc); - return mod.default(); - } - return <>; - })} -
    +
  • + {jsDoc + ? ( +
    + {jsDoc} +
    + ) + : <>} {property.name} {": "} @@ -130,6 +155,34 @@ function* TSInterfaceDef(
    • , ); } + + for (const method of interfaceDef.methods) { + const jsDoc = yield* call(function* (): Operation { + if (method.jsDoc?.doc) { + const mod = yield* useMDX(method.jsDoc?.doc); + return mod.default(); + } + }); + elements.push( +
  • + {jsDoc + ? ( +
    + {jsDoc} +
    + ) + : <>} + {method.name} + + ( + + ) + {": "} + {method.returnType ? : <>} + {";"} +
    • , + ); + } return (
      {elements} @@ -137,21 +190,31 @@ function* TSInterfaceDef( ); } +function FunctionParams({ params }: { params: ParamDef[] }) { + return ( + <> + {params.flatMap((param) => [ + , + ", ", + ]).slice(0, -1)} + + ); +} + function TSParam({ param }: { param: ParamDef; }) { if (param.kind === "identifier") { - switch (param.tsType?.kind) { - case "keyword": - return ( - <> - {param.name} - - {": "} - {param.tsType?.repr} - - ); - } + return ( + <> + {param.name} + + {": "} + {param.tsType ? : <>} + + ); } return <>; } @@ -170,6 +233,21 @@ function TypeDef({ typeDef }: { return ; case "union": return ; + case "fnOrConstructor": + if (typeDef.fnOrConstructor.constructor) { + // TODO(taras): implement + return <> + } else { + return ( + <> + ( + + ) + {" => "} + + + ) + } case "array": return ( <> @@ -205,7 +283,9 @@ function TypeRef({ typeRef }: { <> {"<"} <> - {typeRef.typeParams.map((tp) => )} + {typeRef.typeParams.flatMap(( + tp, + ) => [, ", "]).slice(0, -1)} {">"} @@ -214,3 +294,27 @@ function TypeRef({ typeRef }: { ); } + +function InterfaceTypeParams( + { typeParams }: { typeParams: TsTypeParamDef[] }, +): JSXElement { + return ( + <> + {"<"} + <> + {typeParams.flatMap((param) => { + return [ + <> + {param.name} + {param.constraint + ? + : <>} + , + <>,, + ]; + }).slice(0, -1)} + + {">"} + + ); +} diff --git a/www/components/tokens.tsx b/www/components/tokens.tsx index f46de70..ff86b10 100644 --- a/www/components/tokens.tsx +++ b/www/components/tokens.tsx @@ -5,9 +5,9 @@ export function ClassName({ children }: { children: JSXChild }): JSXElement { } export function Punctuation( - { children, classes }: { children: JSXChild; classes?: string }, + { children, classes, style }: { children: JSXChild; classes?: string; style?: string }, ): JSXElement { - return {children}; + return {children}; } export function Operator({ children }: { children: JSXChild }): JSXElement { From c969031aad01dcb4b08052a306703e348ce4ab79 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Fri, 4 Oct 2024 12:05:35 -0400 Subject: [PATCH 2/3] Only show exports once --- www/components/exports.tsx | 55 +++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/www/components/exports.tsx b/www/components/exports.tsx index db05bdc..029af83 100644 --- a/www/components/exports.tsx +++ b/www/components/exports.tsx @@ -16,7 +16,7 @@ export function Exports({ pkg }: { pkg: Package }): JSXElement { ))} @@ -27,35 +27,46 @@ export function Exports({ pkg }: { pkg: Package }): JSXElement { interface PackageExportOptions { packageName: string; exportName: string; - doc: Array; + docs: Array; } -function PackageExport({ packageName, exportName, doc }: PackageExportOptions) { - const exports = doc.flatMap((doc) => { - if (doc.declarationKind === "export") { - return [ - - {["enum", "typeAlias", "namespace", "interface"].includes(doc.kind) - ? {"type "} - : ""} - {doc.name} - , - ", ", - ]; - } else { - return []; - } - }).slice(0, -1); +function PackageExport( + { packageName, exportName, docs }: PackageExportOptions, +) { + const exports = docs + .filter((doc) => doc.declarationKind === "export"); + + const names = exports.map((doc) => doc.name); + + const unique = exports + .flatMap( + (doc, index) => { + if (names.indexOf(doc.name) === index) { + return [doc]; + } else { + return []; + } + }, + ) + .flatMap((doc) => [ + + {["enum", "typeAlias", "namespace", "interface"].includes(doc.kind) + ? {"type "} + : ""} + {doc.name} + , + ", ", + ]).slice(0, -1); return ( 
             
         import
         {" { "}
-        
        {chunk(exports).map(chunk => 
      • {chunk}
        • )}
      
+        
        {chunk(unique).map(chunk => 
      • {chunk}
        • )}
      
         {"} "}
         {"from "}
         "{join(packageName, exportName)}"

From 97fb90a84951470b5069f62b1236baaa915d1a2b Mon Sep 17 00:00:00 2001
From: Taras Mankovski 
Date: Fri, 4 Oct 2024 12:46:46 -0400
Subject: [PATCH 3/3] Made spacing consistent

---
 deno.json                 |  1 -
 examples/deno.json        |  7 ---
 examples/mod.ts           |  1 -
 examples/use-message.ts   | 29 ------------
 websocket/websocket.ts    |  5 +-
 www/components/api.tsx    | 98 +++++++++++++++++++++++++++------------
 www/components/tokens.tsx | 10 +++-
 www/routes/package.tsx    |  2 +-
 8 files changed, 78 insertions(+), 75 deletions(-)
 delete mode 100644 examples/deno.json
 delete mode 100644 examples/mod.ts
 delete mode 100644 examples/use-message.ts

diff --git a/deno.json b/deno.json
index 750ccbe..328e734 100644
--- a/deno.json
+++ b/deno.json
@@ -29,7 +29,6 @@
     "./deno-deploy",
     "./task-buffer",
     "./tinyexec",
-    "./examples",
     "./websocket"
   ]
 }
diff --git a/examples/deno.json b/examples/deno.json
deleted file mode 100644
index 652f104..0000000
--- a/examples/deno.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "name": "@effection-contrib/examples",
-  "version": "0.1.0",
-  "exports": {
-    ".": "./mod.ts"
-  }
-}
diff --git a/examples/mod.ts b/examples/mod.ts
deleted file mode 100644
index 298b7d8..0000000
--- a/examples/mod.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from "./use-message.ts";
diff --git a/examples/use-message.ts b/examples/use-message.ts
deleted file mode 100644
index 72fc541..0000000
--- a/examples/use-message.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import type { Operation } from "effection";
-
-/**
- * This is an interface
- *
- * ```ts
- * interface Message {
- *  text?: string;
- *  code: number | undefined;
- * }
- * ```
- */
-export interface Message {
-  text?: string;
-  code: number | undefined;
-}
-
-/**
- * This is useMessage function
- *
- * ```ts
- * function useMessage(text?: string): Operation
- * ```
- * @param text
- * @returns
- */
-export function* useMessages(text?: string): Operation {
-  return [{ text, code: undefined }];
-}
\ No newline at end of file
diff --git a/websocket/websocket.ts b/websocket/websocket.ts
index 40cc99d..4cb97c2 100644
--- a/websocket/websocket.ts
+++ b/websocket/websocket.ts
@@ -53,7 +53,7 @@ export interface WebSocketResource
  * @param url - The URL of the target WebSocket server to connect to. The URL must use one of the following schemes: ws, wss, http, or https, and cannot include a URL fragment. If a relative URL is provided, it is relative to the base URL of the calling script. For more detail, see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#url
  *
  * @param prototol - A single string or an array of strings representing the sub-protocol(s) that the client would like to use, in order of preference. If it is omitted, an empty array is used by default, i.e. []. For more details, see
- * 
+ *
  * @returns an operation yielding a {@link WebSocketResource}
  */
 export function useWebSocket(
@@ -163,7 +163,4 @@ export function useWebSocket(
   });
 }
 
-/**
- * @ignore until we can get jsdocs working for type unions
- */
 export type WebSocketData = Parameters[0];
diff --git a/www/components/api.tsx b/www/components/api.tsx
index 5185ae9..59f6131 100644
--- a/www/components/api.tsx
+++ b/www/components/api.tsx
@@ -33,9 +33,7 @@ export function* API({ pkg }: DescriptionProps): Operation {
       elements.push(
         (
           
      
-            
      
-              {yield* Type({ node })}
-            
      
+            {yield* Type({ node })}
             
      
               
             
      
@@ -55,23 +53,25 @@ function* Type({ node }: TypeProps): Operation {
   switch (node.kind) {
     case "function":
       return (
-        
      
-          
-            {node.kind}{" "}
-            {node.name}
-            (
-            
-            ): {node.functionDef.returnType
-              ? 
-              : <>}
-          
-        
      
+        
      
+          
      
+            
+              {node.kind}{" "}
+              {node.name}
+              (
+              
+              ): {node.functionDef.returnType
+                ? 
+                : <>}
+            
+          
      
+        
      
       );
     case "interface":
       return (
-        <>
+        
      
           {/** TODO(taras): figure out why text-nowrap is missing **/}
-          
      
+          
      
             {node.kind} {node.name}
             {node.interfaceDef.typeParams.length > 0
               ? (
@@ -80,7 +80,7 @@ function* Type({ node }: TypeProps): Operation {
                 />
               )
               : <>}
-            {node.interfaceDef.extends
+            {node.interfaceDef.extends.length > 0
               ? (
                 <>
                   {" extends "}
@@ -92,25 +92,40 @@ function* Type({ node }: TypeProps): Operation {
                 
               )
               : <>}
+            
+              {" {"}
+            
           
      
-          
-            {" {"}
-          
           {yield* TSInterfaceDef({ interfaceDef: node.interfaceDef })}
           {"}"}
-        
+        
      
       );
     case "variable":
       return (
-        
      
-          
-        
      
+        
      
+          
      
+            
+          
      
+        
      
+      );
+    case "typeAlias":
+      return (
+        
      
+          
      
+            {"type "}
+            {node.name}
+            {" = "}
+            
+          
      
+        
      
       );
     default:
       return (
-        
      
-          {node.kind} {node.name}
-        
      
+        
      
+          
      
+            {node.kind} {node.name}
+          
      
+        
      
       );
   }
 }
@@ -223,6 +238,20 @@ function TypeDef({ typeDef }: {
   typeDef: TsTypeDef;
 }) {
   switch (typeDef.kind) {
+    case "literal":
+      switch (typeDef.literal.kind) {
+        case "string":
+          return "{typeDef.repr}";
+        case "number":
+          return {typeDef.repr};
+        case "boolean":
+          return {typeDef.repr};
+        case "bigInt":
+          return {typeDef.repr};
+        default:
+          // TODO(taras): implement template
+          return <>;
+      }
     case "keyword":
       if (["number", "string", "boolean", "bigint"].includes(typeDef.keyword)) {
         return {typeDef.keyword};
@@ -236,18 +265,27 @@ function TypeDef({ typeDef }: {
     case "fnOrConstructor":
       if (typeDef.fnOrConstructor.constructor) {
         // TODO(taras): implement
-        return <>
+        return <>;
       } else {
         return (
           <>
             (
-              
+            
             )
             {" => "}
             
           
-        )
+        );
       }
+    case "indexedAccess":
+      return (
+        <>
+          
+          [
+          
+          ]
+        
+      );
     case "array":
       return (
         <>
diff --git a/www/components/tokens.tsx b/www/components/tokens.tsx
index ff86b10..bfad596 100644
--- a/www/components/tokens.tsx
+++ b/www/components/tokens.tsx
@@ -5,9 +5,15 @@ export function ClassName({ children }: { children: JSXChild }): JSXElement {
 }
 
 export function Punctuation(
-  { children, classes, style }: { children: JSXChild; classes?: string; style?: string },
+  { children, classes, style }: {
+    children: JSXChild;
+    classes?: string;
+    style?: string;
+  },
 ): JSXElement {
-  return {children};
+  return (
+    {children}
+  );
 }
 
 export function Operator({ children }: { children: JSXChild }): JSXElement {
diff --git a/www/routes/package.tsx b/www/routes/package.tsx
index 0496059..3760137 100644
--- a/www/routes/package.tsx
+++ b/www/routes/package.tsx
@@ -60,7 +60,7 @@ export function packageRoute(): SitemapRoute {
               
      
             
             
-            
      Documentation
      
+            
      Documentation
      
             {yield* API({ pkg })}