feat: migrate adapter to TypeScript

[gshaowei6]

Closes #49.

This is my submission for the bounty:$10 TypeScript upgrade issue.

What changed:

• moved the adapter implementation from index.js to index.ts
• build CommonJS output and declarations into dist/
• point main and types at the compiled package entrypoints
• keep the existing require() export shape, including .default
• add a package-entrypoint regression test so the compiled JS and .d.ts files are present before publish

Verification:

• npm test
• npm run coverage
• npm pack --dry-run

I can provide payout details privately if this is accepted for the bounty.

Summary by CodeRabbit

• New Features

  • Migrated to TypeScript with comprehensive type definitions, providing enhanced type safety and improved IDE integration.

• Chores

  • Updated package entry points to use pre-built distribution artifacts.
  • Configured TypeScript compilation with automated build pipeline; updated development scripts to compile before testing and packaging.

[coderabbitai]

Warning

Rate limit exceeded

@gshaowei6 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 20 minutes and 12 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 52d3b385-3035-4b92-9ec4-77cd50954f90

📥 Commits

Reviewing files that changed from the base of the PR and between 9b51778 and 1921a15.

📒 Files selected for processing (2)

• index.ts
• spec/test.spec.js

📝 Walkthrough

Walkthrough

The PR migrates the GCSAdapter from JavaScript to TypeScript by replacing index.js with a typed index.ts implementation, adding TypeScript build configuration, updating package metadata to publish compiled artifacts, and validating the distribution structure through test assertions.

Changes

TypeScript Migration for GCSAdapter

Layer / File(s)	Summary
TypeScript GCSAdapter implementation index.ts	Typed configuration interfaces, constructor argument normalization from legacy shapes and environment variables, and Promise-based methods for GCS file operations (create, delete, fetch, URL generation) with directAccess support for public-read ACLs.
TypeScript compiler configuration tsconfig.json	Compilation targeting ES2020, CommonJS output, strict type checking, declaration file emission, esModuleInterop enabled, and dist directory output.
Package entry points and build scripts package.json, .gitignore	Runtime and types entry points updated to dist/index.js and dist/index.d.ts; files whitelist restricts published contents to dist; build and test scripts run TypeScript compilation before execution; dist/ added to gitignore.
Dependency version updates package-lock.json	Updated @types/node to 22.10.2, TypeScript to 5.9.3, undici-types to 6.20.0; peer metadata removed from @babel/core, @octokit/core, marked, and semantic-release transitive dependencies.
Package entrypoint validation tests spec/test.spec.js	Test imports from compiled dist/index.js and validates that package.json main and types point to dist/ artifacts and that referenced files exist on disk after build.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• parse-community/parse-server-gcs-adapter#57: Both PRs modify GCSAdapter file deletion behavior and testing; this PR rewrites the entire adapter to TypeScript while the related PR upgrades the @google-cloud/storage dependency and adds comprehensive unit tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Security Check	⚠️ Warning	Path traversal via unvalidated filenames, type safety issue with directAccess, unsafe error handling with null rejections, unvalidated URL components, missing input validation.	Validate filename parameters to prevent path traversal; coerce directAccess string to boolean; fix error handling in getFileData; validate/encode config URL parameters.
Engage In Review Feedback	⚠️ Warning	Two review feedback comments remain unaddressed: directAccess boolean coercion (lines 78, 129, 182) and null rejection in getFileData (line 172). No commits or discussions show engagement.	Implement the suggested fixes: add toBoolean() conversion for directAccess, resolve(undefined) instead of reject(err) when file doesn't exist, or discuss with reviewer.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat: migrate adapter to TypeScript' begins with the required 'feat:' prefix and clearly describes the main change in the changeset.
Linked Issues check	✅ Passed	The PR implementation aligns with issue #49 requirements: TypeScript migration with GCSAdapterOptions interface, options normalization using environment variables, GCSAdapter class with async methods (createFile, deleteFile, getFileData, getFileLocation), and compiled output with type declarations.
Out of Scope Changes check	✅ Passed	All changes directly support the TypeScript migration objective: .gitignore for build output, index.ts TypeScript implementation, package.json build configuration, tsconfig.json compiler settings, test updates for entry points, and dependency updates for TypeScript tooling.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@index.ts`:
- Around line 163-173: The exists callback currently rejects with the incoming
err (often null) when the file is not found; update the file.exists branch so
that when exists === false you either resolve(undefined) to match the method
signature or reject with a concrete Error (e.g., new Error('file not found')),
instead of rejecting with err; locate the callback where file.exists(...),
file.download(...), resolve and reject are used and change the else branch to
return resolve(undefined) or reject(new Error(...)) so consumers receive a
proper value or Error.
- Around line 78-79: The environment value for GCS_DIRECT_ACCESS is being stored
as a string via fromEnvironmentOrDefault and later used in conditionals
(this._directAccess) so values like "false" are truthy; coerce the option to a
boolean when resolving options: after calling fromEnvironmentOrDefault for the
'directAccess' key, normalize the string (e.g., toLowerCase) and convert common
truthy strings ("true","1","yes") to true and everything else to false, then
assign that boolean into options before returning as ResolvedGCSAdapterOptions
so the later checks (this._directAccess, calls to makePublic(), and public URL
logic) behave correctly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 061446d3-2310-4023-9b9a-609f53f6986d

📥 Commits

Reviewing files that changed from the base of the PR and between f2eae90 and 9b51778.

📒 Files selected for processing (7)

• .gitignore
• index.js
• index.ts
• package-lock.json
• package.json
• spec/test.spec.js
• tsconfig.json

💤 Files with no reviewable changes (1)

• index.js

[gshaowei6]

Follow-up pushed. Current head is 1921a15.

Review fixes addressed:

• GCS_DIRECT_ACCESS=false stays disabled, and an explicit directAccess: false option takes precedence over the environment fallback.
• getFileData() resolves undefined when GCS reports exists=false instead of rejecting with null.
• The latest small follow-up keeps the existing fallback behavior for unrelated options and scopes the new parsing to directAccess.

Local verification after the latest commit: TypeScript compile, Jasmine (9 specs), coverage (9 specs), and git diff --check.

[gshaowei6]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.