Skip to content

Commit 103f3f4

Browse files
osolmazosolmaz
committed
Save context in CLAUDE.md
1 parent bf5a947 commit 103f3f4

File tree

1 file changed

+200
-0
lines changed

1 file changed

+200
-0
lines changed

‎typescript/CLAUDE.md

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# JSON-DOC TypeScript Implementation - Development Notes
2+
3+
## Project Overview
4+
This is a TypeScript implementation of JSON-DOC, which is a JSON schema-based document format similar to Notion's block structure. The implementation programmatically generates TypeScript interfaces from JSON schemas and provides serialization/deserialization functionality.
5+
6+
## Key Requirements and User Instructions
7+
8+
### Primary Requirements
9+
1. **GENERATE TYPES PROGRAMMATICALLY**: All TypeScript interfaces must be generated from JSON schemas - NO hardcoded types allowed
10+
2. **Schema-First Approach**: Similar to Python implementation using datamodel-codegen, TypeScript interfaces are generated from JSON schema files
11+
3. **Full Serialization Support**: Load JSON-DOC objects, process them with proper typing, and serialize back to identical JSON
12+
4. **Test Compatibility**: Implementation must pass comprehensive tests using real example data from schema/page/ex1_success.json
13+
14+
### Critical User Instructions
15+
- **NEVER hardcode enums or types** - everything must be extracted from JSON schemas
16+
- **Use proper libraries** like json-schema-to-typescript for programmatic generation
17+
- **Follow modern TypeScript conventions** with strict typing
18+
- **Ensure tests pass** with the large example file containing complex nested structures
19+
- **Handle JSON with comments** using appropriate parsing (JSON5)
20+
21+
## Implementation Architecture
22+
23+
### Core Files Structure
24+
```
25+
typescript/
26+
├── src/
27+
│ ├── models/
28+
│ │ └── generated/ # All generated TypeScript interfaces
29+
│ │ ├── essential-types.ts # Generated enums and type guards
30+
│ │ ├── block/ # Block-related interfaces
31+
│ │ ├── file/ # File-related interfaces
32+
│ │ ├── page/ # Page interfaces
33+
│ │ └── shared_definitions/
34+
│ ├── serialization/
35+
│ │ └── loader.ts # Serialization/deserialization logic
36+
│ └── utils/
37+
│ └── json.ts # JSON utility functions
38+
├── scripts/
39+
│ └── generate-types.ts # Type generation script
40+
├── tests/
41+
│ └── serialization.test.ts # Comprehensive tests
42+
└── package.json
43+
```
44+
45+
## Type Generation System
46+
47+
### Key Script: `scripts/generate-types.ts`
48+
This script is the heart of the implementation:
49+
50+
1. **JSON Schema Parsing**: Uses JSON5 to handle schemas with comments
51+
2. **Enum Extraction**: Programmatically extracts enums from schema properties
52+
3. **Interface Generation**: Uses json-schema-to-typescript to create TypeScript interfaces
53+
4. **Reference Resolution**: Handles $ref links between schema files
54+
5. **Essential Types Generation**: Creates only necessary enums and type guards
55+
56+
### Generated Types Categories
57+
- **ObjectType**: page, block, user (extracted from schema const values)
58+
- **BlockType**: paragraph, heading_1, etc. (extracted from block schema enums)
59+
- **RichTextType**: text, equation (extracted from rich text schema)
60+
- **FileType**: file, external (extracted from file schema)
61+
- **ParentType**: page_id, block_id, etc.
62+
63+
### Type Guards
64+
Automatically generated type guard functions:
65+
- `isPage()`, `isBlock()` for object types
66+
- `isParagraphBlock()`, `isHeading1Block()` etc. for block types
67+
- `isRichTextText()`, `isRichTextEquation()` for rich text types
68+
- `isExternalFile()`, `isFileFile()` for file types
69+
70+
## Serialization System
71+
72+
### Core Functions in `loader.ts`
73+
- **`loadJsonDoc(obj)`**: Main entry point for loading JSON-DOC objects
74+
- **`loadPage(obj)`**: Processes page objects
75+
- **`loadBlock(obj)`**: Processes block objects with recursive children handling
76+
- **`loadRichText(obj)`**: Processes rich text elements
77+
- **`jsonDocDumpJson(obj)`**: Serializes objects back to JSON
78+
79+
### Factory Pattern
80+
Uses factory functions for different block types:
81+
- `createParagraphBlock()`, `createHeading1Block()`, etc.
82+
- Each factory ensures proper object type assignment
83+
- Maintains type safety throughout the process
84+
85+
## Testing Strategy
86+
87+
### Test Files
88+
1. **Basic serialization tests**: Simple blocks with rich text
89+
2. **Nested block tests**: Complex hierarchical structures
90+
3. **Page serialization tests**: Full page objects with children
91+
4. **Example file test**: Uses real schema/page/ex1_success.json (40k+ tokens)
92+
93+
### Test Requirements
94+
- Load example JSON with comments using JSON5
95+
- Process through loadJsonDoc() function
96+
- Serialize back using jsonDocDumpJson()
97+
- Compare normalized results (excluding null fields like 'link', 'href')
98+
- Must achieve perfect round-trip serialization
99+
100+
## Build and Development
101+
102+
### NPM Scripts
103+
```json
104+
{
105+
"clean": "rm -rf dist",
106+
"build": "tsc",
107+
"generate-types": "ts-node scripts/generate-types.ts",
108+
"test": "jest",
109+
"prepublishOnly": "npm run clean && npm run generate-types && npm run build"
110+
}
111+
```
112+
113+
### Dependencies
114+
- **Production**: ajv, ajv-formats, json5
115+
- **Development**: @types/jest, jest, ts-jest, ts-node, typescript, json-schema-to-typescript
116+
117+
## Critical Implementation Details
118+
119+
### JSON Schema Comment Handling
120+
- Many schema files contain comments (// and /* */)
121+
- Use JSON5.parse() for robust comment handling
122+
- Fallback to manual comment stripping if needed
123+
- Handle trailing commas and control characters
124+
125+
### Enum Value Consistency
126+
- ObjectType enum values must match serialization strings ('block', 'page')
127+
- BlockType enum keys use PascalCase but values remain original ('paragraph', 'to_do')
128+
- Type guards use enum comparisons with fallback to string literals
129+
130+
### Reference Resolution
131+
- Schema files use $ref to reference other schemas
132+
- Script resolves references recursively (max 4 iterations)
133+
- Handles both relative and absolute reference paths
134+
- Creates simplified reference objects for type generation
135+
136+
### Error Handling
137+
- Graceful degradation when schemas can't be parsed
138+
- Fallback to empty objects rather than failing
139+
- Comprehensive error logging for debugging
140+
- Test fallbacks for missing files
141+
142+
## Development Challenges Solved
143+
144+
### 1. JSON Schema Parsing
145+
**Problem**: Schema files contain comments and control characters
146+
**Solution**: JSON5 parser with fallback to manual comment stripping
147+
148+
### 2. Hardcoded Types
149+
**Problem**: User demanded no hardcoded enums
150+
**Solution**: Extract all enum values from JSON schemas programmatically
151+
152+
### 3. Serialization Consistency
153+
**Problem**: Round-trip serialization must produce identical results
154+
**Solution**: Careful handling of null fields, proper factory functions, type normalization
155+
156+
### 4. Complex Example File
157+
**Problem**: Must handle 40k+ token example file with deep nesting
158+
**Solution**: Robust recursive processing, proper memory management, comprehensive testing
159+
160+
## User Feedback and Corrections
161+
162+
### Major User Corrections
163+
1. **"GENERATE THE TYPES PROGRAMMATICALLY, OR ELSE!"** - Led to complete rewrite of type generation
164+
2. **"Use /schema/page/ex1_success.json"** - Required handling large, complex real-world data
165+
3. **"DO NOT FAIL"** - Emphasized importance of robust implementation
166+
167+
### User Expectations
168+
- Zero tolerance for shortcuts or hardcoded values
169+
- Must match Python implementation's functionality
170+
- Comprehensive testing with real data
171+
- Modern TypeScript best practices
172+
173+
## Future Maintenance
174+
175+
### When Adding New Block Types
176+
1. Add schema file to appropriate directory
177+
2. Run `npm run generate-types` to regenerate interfaces
178+
3. Update factory function mapping in loader.ts if needed
179+
4. Add tests for new block type
180+
181+
### When Modifying Schemas
182+
1. Ensure backward compatibility
183+
2. Regenerate types with `npm run generate-types`
184+
3. Run full test suite to verify compatibility
185+
4. Check serialization round-trip still works
186+
187+
### Performance Considerations
188+
- Type generation is build-time, not runtime
189+
- Serialization uses factory pattern for efficiency
190+
- Recursive processing handles deep nesting gracefully
191+
- JSON5 parsing adds minimal overhead
192+
193+
## Key Success Metrics
194+
✅ All types generated from schemas (no hardcoding)
195+
✅ Full test suite passing including example file
196+
✅ Perfect round-trip serialization
197+
✅ Handles complex nested structures
198+
✅ Modern TypeScript with strict typing
199+
✅ Proper error handling and fallbacks
200+
✅ Comprehensive documentation and maintainability

0 commit comments

Comments
 (0)