feat (packages/nhost-js): added functions.post method and improve documentation

[dbarrosop]

PR Type

Enhancement, Documentation, Tests

---

Description

• Add functions.post method for serverless POST requests

• Improve and expand SDK documentation and usage examples

• Enhance error handling and test coverage for all modules

• Add movies table, migration, and seed data for GraphQL demos

---

Changes diagram

flowchart LR
  A["Add functions.post method"] -- "New POST API" --> B["functions/client.ts"]
  B -- "Test & Doc Usage" --> C["functions/__tests__/docstrings.test.ts"]
  B -- "Test & Doc Usage" --> D["index.ts, main.mdx, docs"]
  E["Improve error handling & tests"] -- "Expanded coverage" --> F["auth, storage, graphql, functions tests"]
  G["Add movies table & seed data"] -- "Migration & Metadata" --> H["backend/nhost/migrations, metadata"]
  H -- "Demo data for GraphQL" --> I["graphql/__tests__/docstrings.test.ts"]
  D -- "Reference docs" --> J["docs/reference/javascript/nhost-js/*.mdx"]

Loading

---

Changes walkthrough 📝

	Relevant files
Enhancement	6 files helloworld.ts Add example serverless function for testing POST/GET          +19/-0    public_movies.yaml Add movies table metadata and public select permissions    +16/-0    tables.yaml Register movies table in tables metadata                                  +1/-0      down.sql Migration to drop movies table                                                      +1/-0      up.sql Migration to create movies table and seed demo data            +2/-0      client.ts Add post() method to Functions client for JSON POST requests +57/-0
Configuration changes	4 files nhost.toml Update auth version in Nhost config                                            +1/-1      jest.config.js Add moduleNameMapper for package path aliases                        +9/-0      tsconfig.json Add path aliases for package submodules                                    +11/-1    flake.nix Update nixops and add nix2container to flake inputs            +5/-3
Documentation	11 files .mdx Update module descriptions for accuracy                                    +4/-4      auth.mdx Rewrite and expand Auth module documentation                          +64/-16  functions.mdx Rewrite and expand Functions module documentation, add post() docs +137/-31 graphql.mdx Rewrite and expand GraphQL module documentation with examples +173/-20 main.mdx Update main usage example and documentation                            +22/-11  storage.mdx Rewrite and expand Storage module documentation with examples +104/-15 index.ts Rewrite and expand Auth module JSDoc, update error handling docs +22/-5    index.ts Rewrite and expand Functions module JSDoc, add post() docs +30/-5    index.ts Rewrite and expand GraphQL module JSDoc with examples        +44/-4    index.ts Rewrite main SDK JSDoc, update usage example                          +5/-4      index.ts Rewrite and expand Storage module JSDoc with examples        +24/-5
Tests	10 files auth.test.ts Use package path aliases in auth tests                                      +2/-2      docstrings.test.ts Expand main usage test, add function call, update imports +14/-6    functions.test.ts Add tests for functions.post and improve coverage                +31/-2    graphql.test.ts Use package path aliases in GraphQL tests                                +3/-3      nhost.test.ts Use package path aliases in Nhost client tests                      +1/-1      storage.test.ts Use package path aliases in storage tests                                +3/-3      docstrings.test.ts Expand auth error handling tests and usage examples            +54/-19  docstrings.test.ts Add and expand functions usage and error handling tests    +93/-36  docstrings.test.ts Expand GraphQL usage and error handling tests, add movies demo +332/-20 docstrings.test.ts Expand storage usage and error handling tests                        +92/-14
Dependencies	2 files pnpm-lock.yaml Update Next.js and related dependencies, lockfile changes +42/-41  pnpm-workspace.yaml Add Next.js version override to workspace config                  +1/-0

---

Need help?

Type /help how to ... in the comments thread for any questions about PR-Agent usage.

Check out the documentation for more information.

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review API Consistency The new functions.post method assumes a JSON body and sets Content-Type and Accept headers to application/json. Review if this behavior is consistent with other SDK modules and whether it could cause issues for endpoints expecting different content types or header values. const post = async <T = any>( path: string, body?: unknown, options: RequestInit = {}, ): Promise<FetchResponse<T | string | Blob>> => { // Ensure the method is POST and set the body const requestOptions: RequestInit = { ...options, method: "POST", headers: { Accept: "application/json", "Content-Type": "application/json", ...options.headers, }, body: body ? JSON.stringify(body) : undefined, }; return fetch<T>(path, requestOptions); }; Accept Header Handling The function checks for accept header values but does not handle cases where the header contains multiple values (e.g., "application/json, text/plain"). This could lead to unexpected 400 errors. Consider reviewing header parsing logic for robustness. if (!req.headers.accept || req.headers.accept === "text/plain") { res.setHeader("Content-Type", "text/plain"); return res.status(200).send("Hello, World!"); } // if accept is set to application/json, return JSON if (req.headers.accept === "application/json") { res.setHeader("Content-Type", "application/json"); return res.status(200).json({ message: "Hello, World!" }); } // fail with 400 res.setHeader("Content-Type", "text/plain"); res.status(400).send("Unsupported Accept Header");

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Make Accept header handling robust and case-insensitive The check for req.headers.accept is case-sensitive and does not account for Accept headers with multiple values (e.g., "application/json, text/plain"). This can cause the function to not respond with the expected content type. Consider parsing the Accept header and performing a case-insensitive match for more robust content negotiation. backend/functions/helloworld.ts [5-14] -if (!req.headers.accept || req.headers.accept === "text/plain") { +const accept = (req.headers.accept || "").toLowerCase(); + +if (!accept || accept.includes("text/plain")) { res.setHeader("Content-Type", "text/plain"); return res.status(200).send("Hello, World!"); } - // if accept is set to application/json, return JSON -if (req.headers.accept === "application/json") { +if (accept.includes("application/json")) { res.setHeader("Content-Type", "application/json"); return res.status(200).json({ message: "Hello, World!" }); } Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a real-world bug: the Accept header is case-sensitive and may contain multiple comma-separated values, which the original code does not handle. The improved code makes the check case-insensitive and robust to multiple values, improving API correctness and client compatibility. This is a significant improvement for HTTP content negotiation.	Medium