@orieljs/support 0.1.0-alpha.1 → 0.1.0-alpha.11

package/NOTICE

@@ -7,3 +7,10 @@ This product includes software developed by the Oriel project
 Oriel is licensed under the Apache License, Version 2.0 (see LICENSE).
 The Oriel name and logo are not covered by that license; see TRADEMARKS.md
 (https://github.com/orieljs/framework/blob/main/TRADEMARKS.md).
+
+@orieljs/support (and @orieljs/framework, which bundles it) includes transliteration data from
+voku/portable-ascii (https://github.com/voku/portable-ascii), Copyright (C) 2019 Lars Moelleken, MIT License.
+
+@orieljs/notifications (and @orieljs/framework, which bundles it) includes the HTML and CSS of
+Laravel's default notification mail (laravel/framework, https://github.com/laravel/framework),
+Copyright (c) Taylor Otwell, MIT License.

package/README.md

@@ -0,0 +1,36 @@
+# @orieljs/support
+
+The helpers the rest of Oriel is built on: `Str`, `Arr`, service providers, facades and global helpers, as Laravel's `Illuminate\Support`. It is part of `@orieljs/framework`, which every Oriel app already installs, and is re-exported from it. In an app, import it from `@orieljs/framework`; `@orieljs/support` is also published on its own.
+
+```bash
+npm install @orieljs/framework
+```
+
+```ts title="app/Support/posts.ts"
+import { Str, collect } from '@orieljs/framework'
+import type { Post } from '../Models/Post'
+
+export function card(post: Post) {
+  return {
+    title: Str.of(post.title).trim().title().toString(),
+    excerpt: Str.limit(post.body, 120),
+    url: `/posts/${Str.slug(post.title)}`,
+  }
+}
+
+export function authorIds(posts: Post[]): number[] {
+  return collect(posts).pluck('author_id').unique().all()
+}
+```
+
+`Str` has Laravel's string helpers (`slug()`, `limit()`, `plural()`, `uuid()`, …), and `Str.of()` chains them. `Arr` reads and writes nested values by dotted key (`get()`, `set()`, `has()`), flattens them with `dot()` and picks keys with `only()`. `ServiceProvider` and `facade()` are the base of every component, and the helpers are `app()`, `config()`, `collect()`, `now()`, the async `retry()`, `tap()`, `value()` and `__()`.
+
+Documentation: https://orieljs.vercel.app/docs/helpers
+
+Status: early alpha. APIs will change.
+
+## License
+
+Oriel is open-source software licensed under the Apache License 2.0 (Apache-2.0; see `LICENSE` and `NOTICE`). The Oriel name and logo are trademarks; see `TRADEMARKS.md`.
+
+Website: https://orieljs.vercel.app

package/TRADEMARKS.md

@@ -0,0 +1,33 @@
+# Oriel trademark policy
+
+The Oriel code is open source under the Apache License 2.0. The **Oriel name and logo** are not: the license covers
+the code only (section 6 of the license says so), and the name and logo stay with the project. This page explains
+what you can and can't do with them. The goal is simple: people should always be able to tell what is the real Oriel
+and what isn't.
+
+## You can, without asking
+
+- Use, change, ship and sell the code, as the license allows.
+- Say that your app or package is "built with Oriel", "for Oriel" or "compatible with Oriel".
+- Name a package `oriel-<something>` or `<something>-for-oriel` when it works with Oriel, as long as it is clear that
+  it is not official (for example, don't publish it under the `@orieljs` npm scope).
+- Use the name and logo to write about Oriel, teach it, or link to it, in articles, talks, videos and courses.
+- Use the unmodified logo to point to the project, as it is (no recolouring, cropping or
+  distortion).
+
+## You can't, without written permission
+
+- Call a fork, a modified copy or a competing product "Oriel", or anything likely to be confused with it.
+- Use the name or logo as the name, logo or domain of your own product, company or service.
+- Suggest that the Oriel project made, endorses or supports your work when it doesn't.
+- Sell merchandise with the name or logo.
+
+## Forks
+
+Forks are welcome. Please give yours a different name and logo, keep the `LICENSE` and `NOTICE` files, and say that
+it is based on Oriel.
+
+## Questions
+
+Open an issue at https://github.com/orieljs/framework or email meeeet.dev@gmail.com. If you're unsure whether a use
+is fine, ask; the answer is usually yes.

package/dist/index.d.ts

@@ -1,7 +1,72 @@
-import { ServiceProvider as ServiceProvider$1, Application, Abstract, ClassRegistry as ClassRegistry$1, Class, ConfigRepository } from '@orieljs/contracts';
+import { Collection } from '@orieljs/collections';
 export { collect } from '@orieljs/collections';
+import { ServiceProvider as ServiceProvider$1, Application, Abstract, ClassRegistry as ClassRegistry$1, Class, ConfigRepository } from '@orieljs/contracts';
+
+/**
+ * Laravel's Stringable: a string with Str's helpers as chainable methods, each returning a new Stringable.
+ * `Str.of(' Café ').trim().slug().toString()` is 'cafe'; `request().string('q')` returns one. It prints as its string.
+ */
+declare class Stringable {
+    #private;
+    constructor(value?: string);
+    after(search: string): Stringable;
+    afterLast(search: string): Stringable;
+    append(...values: string[]): Stringable;
+    ascii(): Stringable;
+    before(search: string): Stringable;
+    beforeLast(search: string): Stringable;
+    between(from: string, to: string): Stringable;
+    camel(): Stringable;
+    contains(needles: string | string[]): boolean;
+    endsWith(needles: string | string[]): boolean;
+    /** The same string as `value` (a string or another Stringable). */
+    exactly(value: string | Stringable): boolean;
+    /** The parts between the delimiters, as a Collection (PHP's explode()). */
+    explode(delimiter: string): Collection<string>;
+    finish(cap: string): Stringable;
+    /** Wildcard match, as Str.is(): `*` matches anything. */
+    is(pattern: string): boolean;
+    isEmpty(): boolean;
+    isNotEmpty(): boolean;
+    kebab(): Stringable;
+    lcfirst(): Stringable;
+    /** The number of characters (code points, as PHP's mb_strlen()). */
+    length(): number;
+    limit(limit?: number, end?: string): Stringable;
+    lower(): Stringable;
+    /** Strips whitespace and invisible characters from the start, or the characters given. */
+    ltrim(characters?: string): Stringable;
+    plural(count?: number): Stringable;
+    prepend(...values: string[]): Stringable;
+    /** Replaces every occurrence of the search string (or of each of several) with `replace`. */
+    replace(search: string | string[], replace: string): Stringable;
+    /** Strips whitespace and invisible characters from the end, or the characters given. */
+    rtrim(characters?: string): Stringable;
+    singular(): Stringable;
+    slug(separator?: string): Stringable;
+    snake(delimiter?: string): Stringable;
+    start(prefix: string): Stringable;
+    startsWith(needles: string | string[]): boolean;
+    studly(): Stringable;
+    title(): Stringable;
+    /** PHP's filter_var(FILTER_VALIDATE_BOOLEAN): '1', 'true', 'on' and 'yes' (any case, trimmed) are true. */
+    toBoolean(): boolean;
+    /** PHP's floatval(): the leading number, else 0. */
+    toFloat(): number;
+    /** PHP's intval(): the leading digits, else 0. */
+    toInteger(): number;
+    toJSON(): string;
+    toString(): string;
+    /** Strips whitespace and invisible characters from both ends (Laravel's Str::trim()), or the characters given. */
+    trim(characters?: string): Stringable;
+    ucfirst(): Stringable;
+    upper(): Stringable;
+    value(): string;
+}
 
 declare const Str: {
+    /** Laravel's Str::of(): the value as a Stringable, for chaining: Str.of(title).trim().slug(). */
+    of: (value?: unknown) => Stringable;
     ucfirst: (v: string) => string;
     lcfirst: (v: string) => string;
     studly: (v: string) => string;
@@ -9,11 +74,31 @@ declare const Str: {
     snake: (v: string, delimiter?: string) => string;
     kebab: (v: string) => string;
     title: (v: string) => string;
-    slug: (v: string, separator?: string) => string;
+    /** Laravel's Str::ascii(): the value in plain ASCII ('Café' → 'Cafe', 'Ελληνικά' → 'Ellinika'), as for English. */
+    ascii: (v: string) => string;
+    /**
+     * Laravel's Str::slug(): transliterated to ASCII first (unless `language` is null), '@' read as 'at', then lower-cased
+     * letters and digits joined by the separator: 'Café crème' → 'cafe-creme'. What has no ASCII form is dropped.
+     */
+    slug: (title: string, separator?: string, language?: "en" | null, dictionary?: Readonly<Record<string, string>>) => string;
     plural: (v: string, count?: number) => string;
     singular: (v: string) => string;
     random: (length?: number) => string;
     uuid: () => `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * A version 7 UUID (RFC 9562): the time in milliseconds first, so ids from later milliseconds sort after earlier ones
+     * (within one millisecond the order is random). Throws a TypeError for a time before 1970, after 10889 or invalid.
+     */
+    uuid7: (time?: Date) => string;
+    /**
+     * A ULID: 26 upper-case Crockford characters, ten for the time in milliseconds and sixteen random, so ids from later
+     * milliseconds sort after earlier ones. Throws a TypeError for a time before 1970, after 10889 or invalid.
+     */
+    ulid: (time?: Date) => string;
+    /** Laravel's Str::isUuid(): five groups of hex digits, any version. */
+    isUuid: (value: unknown) => value is string;
+    /** Laravel's Str::isUlid(): 26 Crockford characters in either case, the first at most 7. */
+    isUlid: (value: unknown) => value is string;
     /** Wildcard match: `*` matches anything; everything else is literal. */
     is: (pattern: string, value: string) => boolean;
     startsWith: (v: string, needles: string | string[]) => boolean;
@@ -85,4 +170,68 @@ declare function tap<T>(target: T, callback: (target: T) => void): T;
 /** Calls fn up to `times` times (attempt numbers are 1-based). Rethrows the last error, or the first one `when` rejects. */
 declare function retry<T>(times: number, fn: (attempt: number) => T | Promise<T>, sleepMs?: number | ((attempt: number) => number), when?: (error: unknown) => boolean): Promise<T>;
 
-export { Arr, ClassRegistry, type Facade, type FacadeStatics, ServiceProvider, Str, app, config, facade, now, retry, tap, value };
+/**
+ * Laravel's __(): the line for `key` with `:placeholders` filled (`:name`, `:Name` capitalized, `:NAME` upper-cased),
+ * longest placeholder first. A key with no line comes back as is, so a sentence can be its own key:
+ * __('auth.failed'), __('auth.throttle', { seconds: 30 }), __('A reset link will be sent if the account exists.').
+ */
+declare function __(key: string, replace?: Record<string, string | number>): string;
+
+/**
+ * What a file's bytes show it to be, read from its leading bytes the way PHP's finfo reads them for Laravel (the file
+ * validation rules, and the extension a stored upload gets). The client's file name and MIME type are never consulted.
+ */
+interface DetectedType {
+    /** 'image/png', 'text/plain', …; 'application/octet-stream' when no format matches, 'application/x-empty' for no bytes. */
+    readonly mime: string;
+    /** The extensions that name the type, the usual one first. Empty when the bytes match no format. */
+    readonly extensions: readonly string[];
+}
+declare const JPEG: DetectedType;
+declare const PNG: DetectedType;
+declare const GIF: DetectedType;
+declare const WEBP: DetectedType;
+declare const AVIF: DetectedType;
+declare const BMP: DetectedType;
+declare const SVG: DetectedType;
+declare const PDF: DetectedType;
+declare const HTML: DetectedType;
+declare const XML: DetectedType;
+declare const TEXT: DetectedType;
+declare const UNKNOWN: DetectedType;
+declare const EMPTY: DetectedType;
+/** The raster formats the image rule accepts: Laravel 12's jpg, jpeg, png, gif, bmp and webp, plus AVIF. */
+declare const RASTER_IMAGES: ReadonlySet<string>;
+/** Every format recognised by its bytes other than plain text. */
+declare const BINARY_AND_MARKUP_TYPES: readonly DetectedType[];
+/**
+ * How much of a file is read to tell its type: the window checked for binary bytes (libmagic reads its first megabyte
+ * too). Uploads read this much to be named, so naming and validation see the same bytes.
+ */
+declare const SNIFF_BYTES: number;
+/** The type the bytes show. */
+declare function detectFileType(bytes: Uint8Array): DetectedType;
+
+declare const fileType_AVIF: typeof AVIF;
+declare const fileType_BINARY_AND_MARKUP_TYPES: typeof BINARY_AND_MARKUP_TYPES;
+declare const fileType_BMP: typeof BMP;
+type fileType_DetectedType = DetectedType;
+declare const fileType_EMPTY: typeof EMPTY;
+declare const fileType_GIF: typeof GIF;
+declare const fileType_HTML: typeof HTML;
+declare const fileType_JPEG: typeof JPEG;
+declare const fileType_PDF: typeof PDF;
+declare const fileType_PNG: typeof PNG;
+declare const fileType_RASTER_IMAGES: typeof RASTER_IMAGES;
+declare const fileType_SNIFF_BYTES: typeof SNIFF_BYTES;
+declare const fileType_SVG: typeof SVG;
+declare const fileType_TEXT: typeof TEXT;
+declare const fileType_UNKNOWN: typeof UNKNOWN;
+declare const fileType_WEBP: typeof WEBP;
+declare const fileType_XML: typeof XML;
+declare const fileType_detectFileType: typeof detectFileType;
+declare namespace fileType {
+  export { fileType_AVIF as AVIF, fileType_BINARY_AND_MARKUP_TYPES as BINARY_AND_MARKUP_TYPES, fileType_BMP as BMP, type fileType_DetectedType as DetectedType, fileType_EMPTY as EMPTY, fileType_GIF as GIF, fileType_HTML as HTML, fileType_JPEG as JPEG, fileType_PDF as PDF, fileType_PNG as PNG, fileType_RASTER_IMAGES as RASTER_IMAGES, fileType_SNIFF_BYTES as SNIFF_BYTES, fileType_SVG as SVG, fileType_TEXT as TEXT, fileType_UNKNOWN as UNKNOWN, fileType_WEBP as WEBP, fileType_XML as XML, fileType_detectFileType as detectFileType };
+}
+
+export { Arr, ClassRegistry, type Facade, type FacadeStatics, fileType as FileType, ServiceProvider, Str, Stringable, __, app, config, facade, now, retry, tap, value };