postcss/lib/postcss.d.mts at 8.4.39

mirror of https://github.com/hanzoai/postcss.git synced 2026-09-24 17:01:56 +00:00

Files

T

Remco Haszing cae533107d Fix type definitions

Many files from postcss are exported. Each of this file is written using
the syntax:

```js
module.exports = Thing
```

This should be typed as:

```ts
export = Thing
```

If such a file needs to export additional types, a namespace should be
used.

However, it was typed as:

```ts
export default thing
```

This was solved at the time in #1459 (by me) by adding the following
code to each module:

```js
Thing.default = Thing
```

Whilst affective at the time, this was not the correct solution. The
introduction of the `"module": "node16"` option in TypeScript made this
issue more apparent. I recommend to remove this in a next semver major
release.

Usage has changed as follows:

**cts**

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node16"
  }
}
```

```ts
// Old
import postcss = require('postcss')

postcss.default(/* … */)
```

```ts
// New
import postcss = require('postcss')

postcss(/* … */)
```

**cjs**

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "checkJs": true,
    "module": "commonjs",
    "moduleResolution": "node16"
  }
}
```

```ts
// Old
const postcss = require('postcss')

postcss.default(/* … */)
```

```ts
// New
const postcss = require('postcss')

postcss(/* … */)
```

**mts** / **mjs**

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "module": "node16"
  }
}
```

```ts
// Old
import postcss from 'postcss'

postcss.default(/* … */)
```

```ts
// New
import postcss from 'postcss'

postcss(/* … */)
```

**bundler**

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "module": "esnext",
    "moduleResolution": "node16"
  }
}
```

```ts
// Unchanged
import postcss from 'postcss'

postcss(/* … */)
```

**ES module interop** (Not recommended for library code!)

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "esModuleInterop": true,
    "module": "commonjs",
    "moduleResolution": "node16"
  }
}
```

```ts
// Unchanged
import postcss from 'postcss'

postcss(/* … */)
```

When compiling to CJS, it is still possible to write ESM-like syntax,
for example:

```jsonc
// Same as import postcss = require('postcss')
import * as postcss from 'postcss'
// Named imports from namespaces are allowed
import { root, Root } from 'postcss'
```

The following changes were made to `tsconfig.json`:

- `lib` was specified explicitly. By default, TypeScript includes the
  `dom` types. This is not desirable, it even causes some conflicts with
  types used by Postcss.
- `allowJs` was removed. When this is enabled, TypeScript treats `.d.ts`
  files matching `.js` files as output. This caused some unexpected
  issues where TypeScript simply ignored type errors.
- `skipLibCheck` was removed. Ideally all types just work together. This
  can be added again later if necessary.
- `esModuleInterop` was removed. Enabling this option causes TypeScript
  to allow code that is otherwise invalid. This may be useful for CLIs
  or website, but is dangerous to use for libraries.

Correcting these options also highlighted some issues in the tests.
These have been resolved. `nanodelay@1` has incorrect type definitions,
so it has been marked using `@ts-expect-error` comments.

In `test/errors.ts` were some type errors. These were marked as
`THROWS`, which signals `check-dts` a type error is expected.
This was changed to `@ts-expect-error`, which works too, but it also
works with other TypeScript tooling.

The `Postcss` type was missing some properties. As a side effect of the
corrected types, these are now available. This also affects the `Helper`
type.

Last, but not least, type definitions have been added for `postcss.mjs`.

Closes #1814

2023-02-16 16:17:58 +01:00

73 lines

1.0 KiB

TypeScript

Raw Permalink Blame History

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

 export {
   // postcss function / namespace
   default,
   // Value exports from postcss.mjs
   stringify,
   fromJSON,
   // @ts-expect-error This value exists, but it’s untyped.
   plugin,
   parse,
   list,
   document,
   comment,
   atRule,
   rule,
   decl,
   root,
   CssSyntaxError,
   Declaration,
   Container,
   Processor,
   Document,
   Comment,
   Warning,
   AtRule,
   Result,
   Input,
   Rule,
   Root,
   Node,
   // Type-only exports
   AcceptedPlugin,
   AnyNode,
   AtRuleProps,
   Builder,
   ChildNode,
   ChildProps,
   CommentProps,
   ContainerProps,
   DeclarationProps,
   DocumentProps,
   FilePosition,
   Helpers,
   JSONHydrator,
   Message,
   NodeErrorOptions,
   NodeProps,
   OldPlugin,
   Parser,
   Plugin,
   PluginCreator,
   Position,
   Postcss,
   ProcessOptions,
   RootProps,
   RuleProps,
   Source,
   SourceMap,
   SourceMapOptions,
   Stringifier,
   Syntax,
   TransformCallback,
   Transformer,
   WarningOptions,
   // This is a class, but it’s not re-exported. That’s why it’s exported as type-only here.
   type LazyResult,
 } from './postcss.js'

73 lines 1.0 KiB TypeScript Raw Permalink Blame History Unescape Escape

73 lines

1.0 KiB

TypeScript

Raw Permalink Blame History