{"_id":"@austin-butters/quickschema","name":"@austin-butters/quickschema","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@austin-butters/quickschema","version":"1.0.0","description":"Builds JSON Schema for rigid APIs with interface-like shorthand.","author":{"name":"Austin Butters"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/austin-butters/quickschema.git"},"bugs":{"url":"https://github.com/austin-butters/quickschema/issues"},"keywords":["json","schema","quickschema"],"engines":{"node":">=18"},"type":"module","main":"build/index.js","types":"build/index.d.ts","exports":{".":{"types":"./build/index.d.ts","import":"./build/index.js"}},"sideEffects":false,"devDependencies":{"json-schema":"^0.4.0","typescript":"^5.9.3"},"dependencies":{"@types/json-schema":"^7.0.15"},"scripts":{"build":"npx tsc","test":"npm run build && node --test tests/**/*.test.js","prepublishOnly":"npm run build","prepare":"npm run build"},"gitHead":"a40d576001a595e0d4679f14dbc534c36532874a","_id":"@austin-butters/quickschema@1.0.0","homepage":"https://github.com/austin-butters/quickschema#readme","_nodeVersion":"22.14.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-4iYZtmjY8f9HxNMrukOjgnFlpZo0qjVgb/niT/Timpd8FIMyC+O/IV6/FfLR5jkCuGagYVGvgU335JoZq1QPZQ==","shasum":"1c6e932d77e43d6bc5839ba25e3b7434aae9c857","tarball":"https://registry.npmjs.org/@austin-butters/quickschema/-/quickschema-1.0.0.tgz","fileCount":5,"unpackedSize":16715,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDIVrM2lM+Q9oQ5ChrDp4q0xqeyVeW04aB6ywRP7U2lNAIhAN5nO+D5pl67wxWvvZZCV5BnYdNyY0FCwws50f6PZLAV"}]},"_npmUser":{"name":"austin-butters","email":"buttersaustin2020@gmail.com"},"directories":{},"maintainers":[{"name":"austin-butters","email":"buttersaustin2020@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/quickschema_1.0.0_1763352861573_0.5889102568617501"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-17T04:14:21.515Z","1.0.0":"2025-11-17T04:14:21.770Z","modified":"2025-11-17T04:14:22.047Z"},"maintainers":[{"name":"austin-butters","email":"buttersaustin2020@gmail.com"}],"description":"Builds JSON Schema for rigid APIs with interface-like shorthand.","homepage":"https://github.com/austin-butters/quickschema#readme","keywords":["json","schema","quickschema"],"repository":{"type":"git","url":"git+https://github.com/austin-butters/quickschema.git"},"author":{"name":"Austin Butters"},"bugs":{"url":"https://github.com/austin-butters/quickschema/issues"},"license":"MIT","readme":"# QuickSchema\n\n> **⚠️ Deprecation Notice:** This package will soon be deprecated in favor of an organization-supported scope. No breaking changes will be made.\n\nBuilds JSON Schema for rigid APIs with interface-like shorthand.\n\n## Overview\n\nQuickSchema is an **opinionated** library for generating JSON Schema 7. It uses a **TypeScript interface-like typing syntax** with intentional restrictions, making it feel natural to TypeScript developers while enforcing rigid API structures.\n\nInstead of writing verbose JSON Schema, you write clean, interface-like definitions:\n\n```typescript\n// TypeScript interface\ninterface User {\n  name: string\n  age: number\n  email?: string  // Optional\n}\n\n// QuickSchema (similar syntax, with restrictions)\n$q({\n  name: 'string',\n  age: 'number',\n  'email?': 'string'  // Nullable (required but can be null)\n})\n```\n\nQuickSchema is designed for APIs with **strong, rigid structures** where consistency is key. It intentionally doesn't cover all JSON Schema use cases—instead, it provides a simple, intuitive syntax for the most common patterns.\n\n**Key restriction**: Unlike TypeScript interfaces, properties marked with `?` are still **required** in the JSON (they can be `null`, but cannot be omitted). This enforces rigid API contracts. If you need truly optional properties or full JSON Schema flexibility, use `_q()` to escape into raw JSON Schema, or consider a different library.\n\n## Installation\n\n```bash\nnpm install @austin-butters/quickschema\n```\n\n## Quick Start\n\n```javascript\nimport { $q } from '@austin-butters/quickschema'\n\n// Simple types\nconst stringSchema = $q('string')\n// → { type: 'string' }\n\n// Objects\nconst userSchema = $q({\n  name: 'string',\n  age: 'number',\n  email: 'string'\n})\n// → {\n//     type: 'object',\n//     properties: {\n//       name: { type: 'string' },\n//       age: { type: 'number' },\n//       email: { type: 'string' }\n//     },\n//     required: ['name', 'age', 'email'],\n//     additionalProperties: false\n//   }\n\n// Arrays\nconst tagsSchema = $q(['string'])\n// → { type: 'array', items: { type: 'string' } }\n\n// Nested structures\nconst complexSchema = $q({\n  users: [{\n    name: 'string',\n    'email?': 'string',  // nullable (required but can be null)\n    tags: ['string']\n  }]\n})\n// → {\n//     type: 'object',\n//     properties: {\n//       users: {\n//         type: 'array',\n//         items: {\n//           type: 'object',\n//           properties: {\n//             name: { type: 'string' },\n//             email: { anyOf: [{ type: 'string' }, { type: 'null' }] },\n//             tags: { type: 'array', items: { type: 'string' } }\n//           },\n//           required: ['name', 'email', 'tags'],\n//           additionalProperties: false\n//         }\n//       }\n//     },\n//     required: ['users'],\n//     additionalProperties: false\n//   }\n```\n\n## Usage\n\n### Types\n\n#### `type QSchema`\n\nThe input type for `$q()`. Can be:\n\n- **Primitive strings**: `'string'`, `'number'`, `'boolean'`, `'null'`\n- **Arrays**: `[QSchema]` - an array containing a single schema definition\n- **Objects**: `{ [key: string]: QSchema }` - an object where keys are property names and values are schema definitions\n  - Keys ending with `?` indicate nullable properties (required but can be `null`)\n- **Pre-formatted schemas**: Return value from `_q()` - allows escaping to raw JSON Schema\n\n#### `type QFormatted`\n\nAn alias for `JSONSchema7`. Represents a pre-formatted JSON Schema that bypasses QuickSchema's processing when used with `_q()`.\n\n### Functions\n\n### `$q(schema: QSchema): JSONSchema7`\n\nConverts a `QSchema` shorthand into a full JSON Schema 7 object.\n\n#### Optional Properties (Nullable)\n\nProperties ending with `?` are **required but nullable** (can be `null`, not `undefined`):\n\n```javascript\n$q({\n  name: 'string',\n  'email?': 'string'  // Required, but can be null\n})\n// → {\n//     properties: {\n//       name: { type: 'string' },\n//       email: { anyOf: [{ type: 'string' }, { type: 'null' }] }\n//     },\n//     required: ['name', 'email']  // Both are required!\n//   }\n```\n\n**Important**: QuickSchema doesn't support truly optional properties (omitted from JSON). All properties must be present, but nullable ones can be `null`. If you need truly optional properties, use `_q()` to escape to fully formatted JSON Schema.\n\n#### Nested Structures\n\nQuickSchema supports deep nesting:\n\n```javascript\n$q({\n  user: {\n    profile: {\n      name: 'string',\n      'avatar?': 'string'\n    },\n    tags: ['string']\n  }\n})\n```\n\n### `_q(schema: JSONSchema7): QFormatted`\n\nTakes a `JSONSchema7` object and marks it as pre-formatted, allowing it to bypass QuickSchema's processing when used with `$q()`. Returns a `QFormatted` type that can be passed to `$q()`.\n\nUse this when you need:\n\n- Truly optional properties (not in `required` array)\n- `additionalProperties: true`\n- Custom JSON Schema properties (e.g., `pattern`, `format`, `minLength`, etc.)\n- Properties with `?` in their names\n- Any other JSON Schema feature QuickSchema doesn't support\n\n```javascript\nimport { $q, _q } from '@austin-butters/quickschema'\n\n// Use _q to escape for custom properties\nconst schema = $q({\n  name: 'string',\n  email: _q({ type: 'string', format: 'email' })  // Custom format\n})\n\n// Use _q for truly optional properties\nconst optionalSchema = _q({\n  type: 'object',\n  properties: {\n    name: { type: 'string' },\n    email: { type: 'string' }\n  },\n  required: ['name']  // email is truly optional, can be undefined\n})\n\n// Use _q for additionalProperties: true\nconst flexibleSchema = _q({\n  type: 'object',\n  properties: {\n    name: { type: 'string' }\n  },\n  required: ['name'],\n  additionalProperties: true  // Not possible with $q alone\n})\n```\n\n## Examples\n\n### Basic API Response\n\n```javascript\nconst apiResponse = $q({\n  status: 'string',\n  data: {\n    id: 'number',\n    name: 'string',\n    'description?': 'string',  // Nullable\n    createdAt: 'string'\n  },\n  errors: [{\n    code: 'string',\n    message: 'string'\n  }]\n})\n```\n\n### User Profile with Nested Data\n\n```javascript\nconst userProfile = $q({\n  id: 'number',\n  username: 'string',\n  'email?': 'string',\n  address: {\n    street: 'string',\n    city: 'string',\n    'zip?': 'string'\n  },\n  preferences: {\n    theme: 'string',\n    notifications: 'boolean'\n  }\n})\n```\n\n### Combining with _q for Custom Validation\n\n```javascript\nconst validatedSchema = $q({\n  username: 'string',\n  password: _q({\n    type: 'string',\n    minLength: 8,\n    pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\\\d).+$'\n  }),\n  'email?': _q({\n    type: 'string',\n    format: 'email'\n  })\n})\n```\n\n## Requirements\n\n- Node.js >= 18\n- TypeScript types included\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-42ae220bf8f1d072a35161adcb0e9d9e"}