Extend D1 docs with clarifications for one-way type conversions

[lambrospetrou]

Summary

fixes cloudflare/workers-sdk#8642

Clarify the type conversion happening in D1 to avoid confusion by users. Example: cloudflare/workers-sdk#8642

All the conversions are done in the D1 Worker binding inside the bind() method: https://github.com/cloudflare/workerd/blob/cf9071a1bda90dd3148bb49c38d06f39beb6bd52/src/cloudflare/internal/d1-api.ts#L380

Documentation checklist

• The documentation style guide has been adhered to.
• If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
• Files which have changed name or location have been allocated redirects.

Test

I created the following worker to confirm the conversions.

export default {
	async fetch(request, env) {
		await env.DB.exec('CREATE TABLE IF NOT EXISTS test_blob ( id INTEGER PRIMARY KEY, data BLOB );');

		return new Response(
			JSON.stringify([
				await insert(env.DB, new Uint8Array([1, 2, 3])),
				await insert(env.DB, new Uint8Array([1, 2, 3]).buffer),
				await insert(env.DB, [1, 2, 3]),
				await insert(env.DB, ['hello', 'world'].join(',')),
				await insert(env.DB, 'boomer-string'),
				await insert(env.DB, 1111),
				await insert(env.DB, true),
				await insert(env.DB, false),
				await insert(env.DB, null),
			]),
			{
				headers: { 'Content-Type': 'application/json' },
			}
		);
	},
};

async function insert(db: D1Database, val: any) {
	await db.prepare('INSERT INTO test_blob (data) VALUES (?)').bind(val).run();
	const result = await db.prepare('SELECT data FROM test_blob ORDER BY id DESC LIMIT 1').first();
	const typeofName = typeof result?.data ?? '<unknown>';
	const constructorName = result?.data?.constructor?.name || 'undefined';

	return {
		constructor: constructorName,
		typeof: typeofName,
	};
}

Running that returns:

[
  {
    "constructor": "Array",
    "typeof": "object"
  },
  {
    "constructor": "Array",
    "typeof": "object"
  },
  {
    "constructor": "Array",
    "typeof": "object"
  },
  {
    "constructor": "String",
    "typeof": "string"
  },
  {
    "constructor": "String",
    "typeof": "string"
  },
  {
    "constructor": "Number",
    "typeof": "number"
  },
  {
    "constructor": "Number",
    "typeof": "number"
  },
  {
    "constructor": "Number",
    "typeof": "number"
  },
  {
    "constructor": "undefined",
    "typeof": "object"
  }
]

[hyperlint-ai]

Howdy and thanks for contributing to our repo. The Cloudflare team reviews new, external PRs within two (2) weeks. If it's been two weeks or longer without any movement, please tag the PR Assignees in a comment.

We review internal PRs within 1 week. If it's something urgent or has been sitting without a comment, start a thread in the Developer Docs space internally.

---

PR Change Summary

Extended D1 documentation to clarify one-way type conversions and their implications for users.

• Clarified the one-way nature of type conversions in D1.
• Updated the documentation to include detailed type conversion mappings.
• Provided examples of type conversions in the D1 Worker binding.

Modified Files

• src/content/docs/d1/worker-api/index.mdx

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[lambrospetrou]

@Oxyjun How can we make the footnotes to show on hover? I assume there is some component we can migrate too?

Feel free to checkout and edit this PR directly, BTW.

[Oxyjun]

I'll tackle the footnotes in a separate PR across all the pages. For reference though, this is how the hover footnote works:

Text [^1]

[^1]: Footnote

https://developers.cloudflare.com/style-guide/components/footnotes/

[vicb]

Thanks!