Add documents types design draft

[mohamedsalem401]

No description provided.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3eed54a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[rufuspollock]

LGTM as a first pass.

I'm not yet quite sure how you specify and use the zod annotations and how this then helps consume the objects e.g. i'd like to see an example where i get a Post object (rather than just a File) in getStaticProps ...

e.g.

getStaticProps() {
  markdowndb.get(type=posts) // returns created Post type object rather than File ... somehow
}

[rufuspollock]

Could you provide a short example of what output will look like?

[mohamedsalem401]

@rufuspollock

So I think what you mean by output is either:
1- Error messages if a given file e.g. blog.md is missing a field e.g. author will be Error: Missing 'author' field in 'blog.md' for the 'POST' scheme. Please ensure that the required field is included in the file.

2- Typescript declaration files .d.ts for nextjs Typescript users.

[rufuspollock]

@mohamedsalem401 i meant the first. And will that include the full path to the markdown file etc.

[mohamedsalem401]

@mohamedsalem401 i meant the first. And will that include the full path to the markdown file etc.

I have added the following section in the Design.md

When MarkdownDB loads a Markdown file, it automatically validates the content against the defined schema using Zod. If any field fails validation, MarkdownDB throws an error with a detailed message indicating the specific issue. For instance:

• If the date has an invalid format, it throws an error like this: Error: In 'blog.md' for the 'post' schema. Invalid date format. Please use YYYY-MM-DD format for the 'date' field.
• If a required field is missing, it throws an error like this: Error: Missing 'date' field in 'blog.md' for the 'post' schema.

[rufuspollock]

OK. That's fine.

[mohamedsalem401]

LGTM as a first pass.

I'm not yet quite sure how you specify and use the zod annotations and how this then helps consume the objects e.g. i'd like to see an example where i get a Post object (rather than just a File) in getStaticProps ...

e.g.

getStaticProps() {
  markdowndb.get(type=posts) // returns created Post type object rather than File ... somehow
}

It seems like you're interested in using the Zod annotations to create specific objects, such as a Post object, instead of just a generic File object when using getStaticProps in Next.js.

I think it should be like this:
1- Add type field in every file e.g. type: Post so that we can filter by this type property in the database.
2- Save every file object in the database so that it has the same properties as the scheme defined using zod.
3- To avoid using generic Typescript object we can use Zod to easily generate typescript declaration files.

[rufuspollock]

It seems like you're interested in using the Zod annotations to create specific objects, such as a Post object, instead of just a generic File object when using getStaticProps in Next.js.

I think it should be like this:

1- Add type field in every file e.g. type: Post so that we can filter by this type property in the database.

Yes, or auto-add by folder.

2- Save every file object in the database so that it has the same properties as the scheme defined using zod.

Good question whether we "cast" on the way in or the way out. Probably best on the way in ...

3- To avoid using generic Typescript object we can use Zod to easily generate typescript declaration files.

Right. How would that work ... (and what would usage look like)

[mohamedsalem401]

2. Save every file object in the database so that it has the same properties as the schema defined using Zod.

Good question whether we "cast" on the way in or the way out. Probably best on the way in ...

1. Should we start casting to .json files first or SQL DB first? Or can we make the simplest thing first and then add changes to any of them?
2. What about fields that are common to every file (like tags and links)? Should I add them to every user-defined schema?

3. To avoid using generic TypeScript objects, we can use Zod to easily generate TypeScript declaration files.

Right. How would that work, and what would usage look like?

We can extract the TypeScript type of any schema with z.infer<typeof mySchema>.

const A = z.string();
type AType = z.infer<typeof A>; // string

For more information, refer to the Zod documentation on type inference.

[rufuspollock]

We can extract the TypeScript type of any schema with z.infer.

Yes i knew that. I meant how would it look like from a markdowndb user's code ....

[rufuspollock]

I think this is "good enough to try" so merging now.