Skip to content

refactor: smol type improvement for reference pages #1268

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jun 23, 2025
Merged

refactor: smol type improvement for reference pages #1268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 4 additions & 3 deletions src/lib/syncPagePath.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import type {
GuidesRequestRepresentation,
GuidesResponseRepresentation,
ProjectRepresentation,
ReferenceRequestRepresentation,
ReferenceResponseRepresentation,
} from './types/index.js';

import chalk from 'chalk';
Expand All @@ -15,9 +17,8 @@ import { findPages, type PageMetadata } from './readPage.js';
import { categoryUriRegexPattern, parentUriRegexPattern } from './types/index.js';
import { validateFrontmatter } from './validateFrontmatter.js';

// todo: eventually this type will be used for other page types (e.g., API Reference)
type PageRequestRepresentation = GuidesRequestRepresentation;
type PageResponseRepresentation = GuidesResponseRepresentation['data'];
type PageRequestRepresentation = GuidesRequestRepresentation | ReferenceRequestRepresentation;
type PageResponseRepresentation = GuidesResponseRepresentation['data'] | ReferenceResponseRepresentation['data'];

interface BasePushResult {
filePath: string;
Expand Down
46 changes: 37 additions & 9 deletions src/lib/types/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,36 @@ export const parentUriRegexPattern =
readmeAPIv2Oas.paths['/branches/{branch}/guides'].post.requestBody.content['application/json'].schema.properties
.parent.properties.uri.pattern;

type projectSchema =
(typeof readmeAPIv2Oas)['paths']['/projects/me']['get']['responses']['200']['content']['application/json']['schema'];

type apiKeySchema =
(typeof readmeAPIv2Oas)['paths']['/projects/{subdomain}/apikeys/{api_key_id}']['get']['responses']['200']['content']['application/json']['schema'];

/** Page schemas */
type guidesRequestBodySchema =
(typeof readmeAPIv2Oas)['paths']['/branches/{branch}/guides/{slug}']['patch']['requestBody']['content']['application/json']['schema'];

type guidesResponseBodySchema =
(typeof readmeAPIv2Oas)['paths']['/branches/{branch}/guides/{slug}']['patch']['responses']['200']['content']['application/json']['schema'];

type projectSchema =
(typeof readmeAPIv2Oas)['paths']['/projects/me']['get']['responses']['200']['content']['application/json']['schema'];
type referenceRequestBodySchema =
(typeof readmeAPIv2Oas)['paths']['/branches/{branch}/reference/{slug}']['patch']['requestBody']['content']['application/json']['schema'];

type apiKeySchema =
(typeof readmeAPIv2Oas)['paths']['/projects/{subdomain}/apikeys/{api_key_id}']['get']['responses']['200']['content']['application/json']['schema'];
type referenceResponseBodySchema =
(typeof readmeAPIv2Oas)['paths']['/branches/{branch}/reference/{slug}']['patch']['responses']['200']['content']['application/json']['schema'];

/**
* Derived from our API documentation, this is the schema for the `project` object
* as we receive it to the ReadMe API.
*/
export type ProjectRepresentation = FromSchema<projectSchema, { keepDefaultedPropertiesOptional: true }>;

/**
* Derived from our API documentation, this is the schema for the API key object
* as we receive it to the ReadMe API.
*/
export type APIKeyRepresentation = FromSchema<apiKeySchema, { keepDefaultedPropertiesOptional: true }>;

/**
* Derived from our API documentation, this is the schema for the `guides` object
Expand All @@ -44,13 +63,22 @@ export type GuidesResponseRepresentation = FromSchema<
>;

/**
* Derived from our API documentation, this is the schema for the `project` object
* as we receive it to the ReadMe API.
* Derived from our API documentation, this is the schema for the `reference` object
* as we send it to the ReadMe API.
*
* This is only for TypeScript type-checking purposes — we use ajv
* to validate the user's schema during runtime.
*/
export type ProjectRepresentation = FromSchema<projectSchema, { keepDefaultedPropertiesOptional: true }>;
export type ReferenceRequestRepresentation = FromSchema<
referenceRequestBodySchema,
{ keepDefaultedPropertiesOptional: true }
>;

/**
* Derived from our API documentation, this is the schema for the API key object
* Derived from our API documentation, this is the schema for the `reference` object
* as we receive it to the ReadMe API.
*/
export type APIKeyRepresentation = FromSchema<apiKeySchema, { keepDefaultedPropertiesOptional: true }>;
export type ReferenceResponseRepresentation = FromSchema<
referenceResponseBodySchema,
{ keepDefaultedPropertiesOptional: true }
>;
Loading