feat(types): generate types for imgix url params

Author: JamieMason

.gitignore

@@ -0,0 +1,108 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# Next.js build output
+.next
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and *not* Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# pre-build artefacts
+src/generated
+*.tgz

.prettierignore

@@ -0,0 +1 @@
+*.md

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "arrowParens": "always",
+  "printWidth": 80,
+  "proseWrap": "always",
+  "singleQuote": true,
+  "trailingComma": "all"
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Jamie Mason
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,40 @@
+# typescript-imgix-url-params
+
+> TypeScript definitions of imgix's URL parameters.
+
+![NPM version](http://img.shields.io/npm/v/typescript-imgix-url-params.svg?style=flat-square)](https://www.npmjs.com/package/typescript-imgix-url-params)
+[![NPM downloads](http://img.shields.io/npm/dm/typescript-imgix-url-params.svg?style=flat-square)](https://www.npmjs.com/package/typescript-imgix-url-params)
+[![Build Status](https://img.shields.io/github/workflow/status/JamieMason/typescript-imgix-url-params/ci)](https://github.com/JamieMason/typescript-imgix-url-params/actions)
+[![Maintainability](https://api.codeclimate.com/v1/badges/516439365fdd0e3c6526/maintainability)](https://codeclimate.com/github/JamieMason/typescript-imgix-url-params/maintainability)
+
+## 🌩 Installation
+
+```bash
+npm install --save-dev typescript-imgix-url-params
+```
+
+## ⚠️ Status
+
+This package was created on 15 Nov 2022, it is new but please give it a try and
+[give your feedback](https://github.com/JamieMason/typescript-imgix-url-params/issues/new).
+
+## 🕹 Usage
+
+```ts
+import type { ImgixUrl } from 'typescript-imgix-url-params';
+
+const params: Partial<ImgixUrl.Params> = {
+  w: 100,
+  h: 100,
+  fm: 'pjpg',
+};
+```
+
+## ⚙️ Contributing
+
+To update this package we regenerate the schema based on the latest contents from https://github.com/imgix/imgix-url-params:
+
+1. Bump `imgix-url-params` in package.json.
+1. `yarn install`
+1. `yarn build`
+1. `npm publish .`

package.json

@@ -0,0 +1,32 @@
+{
+  "name": "typescript-imgix-url-params",
+  "description": "TypeScript definitions of imgix's URL parameters",
+  "version": "0.0.0",
+  "author": "Jamie Mason <jamie@foldleft.io> (https://github.com/JamieMason)",
+  "bugs": "https://github.com/JamieMason/typescript-imgix-url-params/issues",
+  "devDependencies": {
+    "@types/node": "18.11.9",
+    "@types/prettier": "2.7.1",
+    "imgix-url-params": "11.13.0",
+    "prettier": "2.7.1",
+    "ts-node": "10.9.1",
+    "typescript": "4.8.4"
+  },
+  "files": [
+    "dist/index.d.ts"
+  ],
+  "homepage": "https://github.com/JamieMason/typescript-imgix-url-params#readme",
+  "keywords": [
+    "imgix",
+    "types",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": "JamieMason/typescript-imgix-url-params.git",
+  "scripts": {
+    "build": "rm -rf dist && ts-node src/build.ts",
+    "prebuild": "rm -rf src/generated && ts-node src/generate-schema.ts",
+    "prepack": "yarn run build"
+  },
+  "types": "dist/index.d.ts"
+}

src/build.ts

@@ -0,0 +1,18 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { format } from 'prettier';
+import { getSource } from './get-source';
+
+const dirPath = resolve(__dirname, '../dist');
+const filePath = resolve(__dirname, '../dist/index.d.ts');
+const source = getSource();
+
+mkdirSync(dirPath, { recursive: true });
+
+writeFileSync(
+  filePath,
+  format(source, {
+    parser: 'typescript',
+  }),
+  'utf8',
+);

src/generate-schema.ts

@@ -0,0 +1,22 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { format } from 'prettier';
+
+const schema = require('imgix-url-params/dist/parameters');
+const dirPath = resolve(__dirname, 'generated');
+const filePath = resolve(__dirname, 'generated/schema.ts');
+const source = `
+export type Schema = typeof schema;
+
+export const schema = ${JSON.stringify(schema)} as const;
+`;
+
+mkdirSync(dirPath, { recursive: true });
+
+writeFileSync(
+  filePath,
+  format(source, {
+    parser: 'typescript',
+  }),
+  'utf8',
+);

src/get-source.ts

@@ -0,0 +1,116 @@
+import { schema, Schema } from './generated/schema';
+
+type Params = Schema['parameters'];
+type ParamSpec = Params[keyof Params];
+type Expects = ParamSpec['expects'];
+type Expect = Expects[number];
+type CategoryValues = Schema['categoryValues'];
+type CategoryValue = CategoryValues[number];
+
+export function getSource(): string {
+  return `
+  export namespace ImgixUrl {
+    ${getTypes()}
+  }
+  `;
+}
+
+export function getTypes(): string {
+  const allEntries: [string, ParamSpec][] = Object.entries(schema.parameters);
+  return [
+    getHexColorType(),
+    getColorKeywordValueType(schema),
+    getFontValueType(schema),
+    ...schema.categoryValues.map(
+      (category) =>
+        `/** @see {@link https://docs.imgix.com/apis/rendering/${category}} */
+        ${getParamsInterface(
+          getCategoryInterfaceName(category),
+          allEntries.filter(([_key, value]) => value.category === category),
+        )}`,
+    ),
+    getImgixUrlParamsType(schema),
+  ].join('\n\n');
+}
+
+function getImgixUrlParamsType(schema: Schema): string {
+  return `
+  /** @see {@link https://docs.imgix.com/apis/rendering} */
+  export type Params = ${schema.categoryValues
+    .map((category) => getCategoryInterfaceName(category))
+    .join(' & ')}`;
+}
+
+function getCategoryInterfaceName(category: CategoryValue): string {
+  return `${kebabToPascalCase(category)}Params`;
+}
+
+function kebabToPascalCase(kebab: string): string {
+  return kebab
+    .split('-')
+    .map((s) => `${s.charAt(0).toUpperCase()}${s.slice(1)}`)
+    .join('');
+}
+
+function getParamsInterface(
+  name: string,
+  entries: [string, ParamSpec][],
+): string {
+  const props: string[] = entries.map(([key, value]) => {
+    const type = getPropTypes(value);
+    const tsdocLines = [
+      value.short_description,
+      'url' in value && `@see {@link ${value.url}}`,
+    ]
+      .filter(Boolean)
+      .map((line) => ` * ${line}`);
+    const tsdoc = ['/**', ...tsdocLines, ' */'].join('\n');
+    return [tsdoc, `'${key}': ${type};`].join('\n');
+  });
+
+  return [`export interface ${name} {`, ...props, '}'].join('\n\n');
+}
+
+function getHexColorType(): string {
+  return 'export type HexColor = `#${string}`';
+}
+
+function getColorKeywordValueType(schema: Schema): string {
+  return `export type ColorKeywordValue = ${schema.colorKeywordValues
+    .map((s) => `'${s}'`)
+    .join(' | ')}`;
+}
+
+function getFontValueType(schema: Schema): string {
+  return `export type FontValue = ${schema.fontValues
+    .map((s) => `'${s}'`)
+    .join(' | ')}`;
+}
+
+function getPropTypes({ expects }: ParamSpec): string {
+  if (!Array.isArray(expects)) return 'unknown';
+  return Array.from(new Set(expects.map((expect) => getPropType(expect)))).join(
+    ' | ',
+  );
+}
+
+function getPropType(expect: Expect): string {
+  if (!expect || typeof expect !== 'object') return 'unknown';
+  if ('0' in expect || '1' in expect || '2' in expect || '3' in expect)
+    return 'unknown';
+  if (expect.type === 'boolean') return 'boolean';
+  if (expect.type === 'color_keyword') return 'ColorKeywordValue';
+  if (expect.type === 'font') return 'FontValue';
+  if (expect.type === 'hex_color') return 'HexColor';
+  if (expect.type === 'integer') return 'number';
+  if (expect.type === 'list')
+    return expect.possible_values.map((s) => `'${s}'`).join(' | ');
+  if (expect.type === 'number') return 'number';
+  if (expect.type === 'path') return 'string';
+  if (expect.type === 'ratio') return 'number';
+  if (expect.type === 'string') return 'string';
+  if (expect.type === 'timestamp') return 'string';
+  if (expect.type === 'unit_scalar') return 'number';
+  if (expect.type === 'url') return 'string';
+  return 'unknown';
+}