docs: add updateMany/bulkUpdate JSDoc and method ordering pipeline

[wixysam]

Summary

• Add comprehensive JSDoc for the new updateMany() and bulkUpdate() entity methods, including cross-links between all three update methods, links to MongoDB query/update operator docs, and realistic examples
• Register UpdateManyResult type in the doc generation pipeline (types-to-expose.json, types-to-delete-after-processing.json)
• Add a reusable method ordering post-processor driven by method-order.json — reorders ### method() blocks in generated MDX based on a config file, and relocates displaced type-definition blocks to the ## Type Definitions section
• Fix truncated ParamField types for intersection types (e.g. Partial<...> & object[] → (Partial<T> & { id: string })[])

Method ordering mechanism

New file scripts/mintlify-post-processing/method-order.json maps MDX filenames to desired method order. To reorder methods in any other module, just add a new key. The post-processor also fixes a pre-existing issue where type definitions (EntityRecord, EntityTypeRegistry, SortField) appeared in the methods TOC section instead of under Type Definitions.

Test plan

• npm run create-docs-local runs without errors
• Entities page methods appear in CRUD-grouped order
• Type definitions appear under ## Type Definitions, not in methods section
• Other modules (agents, auth, connectors, etc.) are unaffected

Made with Cursor

[claude]

Claude finished @wixysam's task —— View job

---

Claude Code is reviewing this PR...

Review Tasks

• Review JSDoc additions in entities.types.ts
• Review method ordering post-processor implementation
• Check configuration file changes
• Analyze code quality and best practices
• Identify potential bugs or issues
• Consider performance implications
• Review security aspects
• Assess test coverage

JSDoc Review

The JSDoc additions for updateMany() and bulkUpdate() are excellent:

Strengths

• Clear differentiation: The documentation clearly distinguishes between the three update methods and their use cases
• Rich examples: Multiple realistic examples demonstrate different scenarios (basic usage, query operators, batching, etc.)
• External links: Links to MongoDB documentation for query/update operators are helpful
• Cross-references: Using {@linkcode} to link between related methods improves navigation
• Consistent format: Follows the same documentation style as existing methods

Code Quality

The method ordering post-processor (file-processing.js) is well-implemented:

Strengths

• Modular design: The reorderMethods() function is cleanly separated and reusable
• Configuration-driven: The method-order.json allows easy customization for different modules
• Smart handling: Preserves relative order of unlisted methods and relocates displaced type definitions
• Non-intrusive: Only processes files that have a configuration entry

Minor Suggestions

1. Edge case handling: The processor assumes *** as section separators. Consider adding a comment documenting this requirement
2. Type safety: The configuration files (types-to-expose.json, etc.) could benefit from JSON schema validation

Performance & Security

• Performance: The post-processor reads and writes files synchronously, which is fine for a build-time script
• Security: No security concerns - the script only processes local documentation files
• Test coverage: The PR mentions testing with npm run create-docs-local, which is appropriate for a documentation tool

Overall Assessment

This is a high-quality PR that adds comprehensive documentation for the new bulk update methods and implements a clever solution for method ordering in generated docs. The code is clean, well-structured, and follows good practices. The documentation improvements will significantly help developers understand and use these methods correctly.

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.22-pr.144.d5f4c16

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.22-pr.144.d5f4c16"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.22-pr.144.d5f4c16"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.22-pr.144.d5f4c16
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[claude]

Claude finished @wixysam's task —— View job

---

Claude Code reviewed this PR

Review Tasks

• Review JSDoc additions in entities.types.ts
• Review method ordering post-processor implementation
• Check configuration file changes
• Analyze code quality and best practices
• Identify potential bugs or issues
• Consider performance implications
• Review security aspects
• Assess test coverage

JSDoc Review

The JSDoc additions for updateMany() and bulkUpdate() are well-written and comprehensive:

Strengths

• Clear differentiation: Each update method (update, updateMany, bulkUpdate) has clear use case descriptions and cross-references via {@linkcode}
• Practical examples: Multiple examples demonstrate different scenarios including basic usage, query operators, update operators, and batch processing
• External references: Links to MongoDB documentation for query/update operators are helpful
• Consistent formatting: Follows the same documentation style as existing methods

Improvement Suggestion

I agree with @danshw's review comment. The updateMany documentation should emphasize the importance of filter exclusions to avoid re-updating records. The current example at lines 459-475 demonstrates this pattern correctly (filtering by status: 'pending' before setting to 'processed'), but this critical detail deserves explicit mention in the main documentation.

Suggested enhancement for line 406:

* Results are batched in groups of up to 500. When `has_more` is `true`
* in the response, call `updateMany` again with the same query to update
* the next batch. **Important**: Design your query to exclude already-updated 
* records to avoid infinite loops. For example, filter by `status: 'pending'`
* when setting status to `'processed'`, or by `active: true` when setting
* to `false`.

Method Ordering Post-Processor

The new method ordering functionality in file-processing.js is well-implemented:

Implementation Review

• Configuration-driven design: The method-order.json file allows easy customization without code changes
• Smart section handling: The reorderMethods() function correctly handles:
  • Method sections split by *** separators
  • Preservation of non-method sections
  • Relocation of displaced type definitions to the correct TOC section
  • Maintaining relative order of unlisted methods

Code Quality Observations

• Regex pattern for method detection: /^### (\w+)\(\)/m correctly identifies method headings
• Safe array manipulation: Uses slice operations to avoid mutating during iteration
• Type definition relocation: Correctly identifies and moves type definitions that appear between method sections

Configuration Changes

The configuration changes are appropriate and well-structured:

types-to-expose.json

• Added UpdateManyResult type for the new bulk update functionality
• Maintains alphabetical ordering for easy maintenance

types-to-delete-after-processing.json

• Correctly includes UpdateManyResult to prevent it from appearing in the navigation while still being available for inline documentation

method-order.json

• New configuration file establishing CRUD-grouped method order
• Logical progression: single read → bulk read → create → update → delete operations
• updateMany and bulkUpdate properly positioned after update

Code Quality

Overall, the code quality is excellent:

Best Practices Followed

• DRY principle: Common logic extracted into reusable functions
• Clear variable naming: orderedNames, methodsHeadingRe, etc. are self-documenting
• Proper error handling: Graceful fallbacks when configuration files are missing
• Functional approach: Using map, filter, and sort for data transformations

Minor Suggestions

1. Edge case documentation: The *** separator dependency in reorderMethods() could use a comment explaining this requirement
2. Type annotations: While this is JavaScript, JSDoc type annotations for function parameters would improve maintainability

Potential Issues

CleanupTruncatedParamTypes Fix

The new cleanupTruncatedParamTypes() function addresses a TypeDoc rendering issue where (Partial<T> & { id: string })[] gets truncated to Partial<...> & object[]. The fix is correct but hardcoded:

content.replace(
  /type="Partial<\.\.\.> & object\[\]"/g,
  'type="(Partial<T> & { id: string })[]"'
);

Potential issue: This assumes all truncated Partial<...> & object[] types specifically have { id: string }. If other intersection types get truncated differently in the future, they won't be handled.

Suggestion: Consider making this more generic or adding a comment explaining this specific case applies to bulkUpdate's data parameter.

Method Ordering Edge Cases

The reorderMethods() function assumes methods are separated by ***. If TypeDoc's output format changes or if manual edits break this pattern, method ordering could fail silently.

Mitigation: The code handles this gracefully by returning unmodified content if no methods are found, so this is low risk.

Performance Considerations

The post-processing script performs well for documentation generation:

Efficient File Processing

• Single-pass reads: Files are read once and processed in memory
• Synchronous I/O: Appropriate for build-time scripts where parallelization isn't critical
• Early returns: Functions like reorderMethods() return early when no changes are needed

Scalability

• Linear complexity: Processing scales linearly with the number of documentation files
• Memory usage: Entire file contents are loaded into memory, but documentation files are typically small
• No performance bottlenecks: Regex operations and array manipulations are on small datasets

Build Time Impact

The script adds minimal overhead to the documentation build process. The multiple processing passes (link fixing, signature cleanup, method ordering, etc.) are justified by the improved documentation quality.

Security Considerations

The changes introduce no security concerns:

Documentation-Only Changes

• All modifications are to JSDoc comments and documentation processing scripts
• No runtime code changes that could introduce vulnerabilities
• No user input processing or external data handling

Build Script Security

• File system access: Limited to reading/writing documentation files in controlled directories
• No external dependencies: Uses only Node.js built-in modules (fs, path)
• Path traversal protection: Uses path.join() for safe path construction

Test Coverage

Current Testing

The PR mentions successful testing with npm run create-docs-local, which validates:

• TypeDoc generation completes without errors
• Post-processing script runs successfully
• Method ordering works as expected
• Type definitions are properly relocated

Suggestions for Enhanced Testing

1. Regression tests: Consider adding tests to verify the post-processor handles edge cases:

   • Missing *** separators
   • Methods not matching the regex pattern
   • Empty or malformed configuration files

2. Visual regression: Since this affects documentation rendering, consider spot-checking the generated MDX output in Mintlify

3. Configuration validation: Add JSON schema validation for configuration files to catch typos early

Summary

This is a high-quality PR that significantly improves the SDK documentation. The new JSDoc for bulk update methods is comprehensive and well-structured. The method ordering post-processor is a clever solution that will improve documentation readability by grouping related CRUD operations together.

The only significant feedback is to incorporate @danshw's suggestion about emphasizing query design to avoid re-processing records in batched updates. All other observations are minor suggestions for future improvements.

The code is production-ready and will enhance the developer experience for SDK users.