Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documents types design draft #77

Merged
merged 6 commits into from
Dec 8, 2023
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ dist/
markdown.db
*.tgz
.markdowndb/
.next/
mohamedsalem401 marked this conversation as resolved.
Show resolved Hide resolved
36 changes: 36 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
### Define Your Schema with Zod Scheming

MarkdownDB leverages the powerful Zod library for schema definition, allowing you to specify the structure and validation rules for your Markdown content. Below is an example configuration demonstrating the usage of Zod to define a schema for a blog post with a mandatory `date` field.

```javascript
// markdowndb.config.js
import { z } from "zod";

module.exports = {
mohamedsalem401 marked this conversation as resolved.
Show resolved Hide resolved
schemas: z.object({
post: {
date: z.string().refine((value) => /\d{4}-\d{2}-\d{2}/.test(value), {
message: "Invalid date format. Please use YYYY-MM-DD.",
}),
// Add more fields as needed, each with its own validation rules
// Example:
// title: z.string().min(1, "Title must have at least 1 character"),
// content: z.string(),
},
// Define additional schemas for different content types
// Example:
// page: {
// author: z.string(),
// text: z.string(),
// },
}),
};
```

In this example, the `post` schema is defined using Zod's `object` method, specifying the structure of the content. The `date` field is required and must adhere to the specified date format using Zod's `string` and `refine` methods for custom validation.

### How Validation Works
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK. That's fine.


When you load a Markdown file using MarkdownDB, it automatically validates the content against the defined schema using Zod. If the validation fails for any field, MarkdownDB will throw an error, providing detailed error messages. This helps you quickly identify and rectify issues, ensuring your Markdown content adheres to the specified structure and validation rules.

Feel free to extend the schema by adding more fields and their respective validation rules as needed for your specific use case. This flexibility allows you to define complex structures and ensure the integrity of your data.
Loading