index.d.ts 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246
  1. export interface Options {
  2. /**
  3. @default '-'
  4. @example
  5. ```
  6. import slugify from '@sindresorhus/slugify';
  7. slugify('BAR and baz');
  8. //=> 'bar-and-baz'
  9. slugify('BAR and baz', {separator: '_'});
  10. //=> 'bar_and_baz'
  11. slugify('BAR and baz', {separator: ''});
  12. //=> 'barandbaz'
  13. ```
  14. */
  15. readonly separator?: string;
  16. /**
  17. Make the slug lowercase.
  18. @default true
  19. @example
  20. ```
  21. import slugify from '@sindresorhus/slugify';
  22. slugify('Déjà Vu!');
  23. //=> 'deja-vu'
  24. slugify('Déjà Vu!', {lowercase: false});
  25. //=> 'Deja-Vu'
  26. ```
  27. */
  28. readonly lowercase?: boolean;
  29. /**
  30. Convert camelcase to separate words. Internally it does `fooBar` → `foo bar`.
  31. @default true
  32. @example
  33. ```
  34. import slugify from '@sindresorhus/slugify';
  35. slugify('fooBar');
  36. //=> 'foo-bar'
  37. slugify('fooBar', {decamelize: false});
  38. //=> 'foobar'
  39. ```
  40. */
  41. readonly decamelize?: boolean;
  42. /**
  43. Add your own custom replacements.
  44. The replacements are run on the original string before any other transformations.
  45. This only overrides a default replacement if you set an item with the same key, like `&`.
  46. Add a leading and trailing space to the replacement to have it separated by dashes.
  47. @default [ ['&', ' and '], ['🦄', ' unicorn '], ['♥', ' love '] ]
  48. @example
  49. ```
  50. import slugify from '@sindresorhus/slugify';
  51. slugify('Foo@unicorn', {
  52. customReplacements: [
  53. ['@', 'at']
  54. ]
  55. });
  56. //=> 'fooatunicorn'
  57. slugify('foo@unicorn', {
  58. customReplacements: [
  59. ['@', ' at ']
  60. ]
  61. });
  62. //=> 'foo-at-unicorn'
  63. slugify('I love 🐶', {
  64. customReplacements: [
  65. ['🐶', 'dogs']
  66. ]
  67. });
  68. //=> 'i-love-dogs'
  69. ```
  70. */
  71. readonly customReplacements?: ReadonlyArray<[string, string]>;
  72. /**
  73. If your string starts with an underscore, it will be preserved in the slugified string.
  74. Sometimes leading underscores are intentional, for example, filenames representing hidden paths on a website.
  75. @default false
  76. @example
  77. ```
  78. import slugify from '@sindresorhus/slugify';
  79. slugify('_foo_bar');
  80. //=> 'foo-bar'
  81. slugify('_foo_bar', {preserveLeadingUnderscore: true});
  82. //=> '_foo-bar'
  83. ```
  84. */
  85. readonly preserveLeadingUnderscore?: boolean;
  86. /**
  87. If your string ends with a dash, it will be preserved in the slugified string.
  88. For example, using slugify on an input field would allow for validation while not preventing the user from writing a slug.
  89. @default false
  90. @example
  91. ```
  92. import slugify from '@sindresorhus/slugify';
  93. slugify('foo-bar-');
  94. //=> 'foo-bar'
  95. slugify('foo-bar-', {preserveTrailingDash: true});
  96. //=> 'foo-bar-'
  97. ```
  98. */
  99. readonly preserveTrailingDash?: boolean;
  100. /**
  101. Preserve certain characters.
  102. It cannot contain the `separator`.
  103. For example, if you want to slugify URLs, but preserve the HTML fragment `#` character, you could set `preserveCharacters: ['#']`.
  104. @default []
  105. @example
  106. ```
  107. import slugify from '@sindresorhus/slugify';
  108. slugify('foo_bar#baz', {preserveCharacters: ['#']});
  109. //=> 'foo-bar#baz'
  110. ```
  111. */
  112. readonly preserveCharacters?: string[];
  113. }
  114. /**
  115. Slugify a string.
  116. @param string - String to slugify.
  117. @example
  118. ```
  119. import slugify from '@sindresorhus/slugify';
  120. slugify('I ♥ Dogs');
  121. //=> 'i-love-dogs'
  122. slugify(' Déjà Vu! ');
  123. //=> 'deja-vu'
  124. slugify('fooBar 123 $#%');
  125. //=> 'foo-bar-123'
  126. slugify('я люблю единорогов');
  127. //=> 'ya-lyublyu-edinorogov'
  128. ```
  129. */
  130. export default function slugify(string: string, options?: Options): string;
  131. export interface CountableSlugify {
  132. /**
  133. Reset the counter.
  134. @example
  135. ```
  136. import {slugifyWithCounter} from '@sindresorhus/slugify';
  137. const slugify = slugifyWithCounter();
  138. slugify('foo bar');
  139. //=> 'foo-bar'
  140. slugify('foo bar');
  141. //=> 'foo-bar-2'
  142. slugify.reset();
  143. slugify('foo bar');
  144. //=> 'foo-bar'
  145. ```
  146. */
  147. reset: () => void;
  148. /**
  149. Returns a new instance of `slugify(string, options?)` with a counter to handle multiple occurrences of the same string.
  150. @param string - String to slugify.
  151. @example
  152. ```
  153. import {slugifyWithCounter} from '@sindresorhus/slugify';
  154. const slugify = slugifyWithCounter();
  155. slugify('foo bar');
  156. //=> 'foo-bar'
  157. slugify('foo bar');
  158. //=> 'foo-bar-2'
  159. slugify.reset();
  160. slugify('foo bar');
  161. //=> 'foo-bar'
  162. ```
  163. __Use case example of counter__
  164. If, for example, you have a document with multiple sections where each subsection has an example.
  165. ```
  166. ## Section 1
  167. ### Example
  168. ## Section 2
  169. ### Example
  170. ```
  171. You can then use `slugifyWithCounter()` to generate unique HTML `id`'s to ensure anchors will link to the right headline.
  172. */
  173. (string: string, options?: Options): string;
  174. }
  175. export function slugifyWithCounter(): CountableSlugify;