@zinaid/types 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,3 @@
+# Zinaid JS Types Package
+
+Utility TypeScript types for @zinaid packages and Laravel HTTP responses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zinaid/types",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Utility TypeScript types for @zinaid packages and Laravel HTTP responses.",
   "type": "module",
   "types": "src/index.d.ts",
@@ -9,7 +9,7 @@
   "license": "MIT",
   "sideEffects": false,
   "files": [
-    "dist"
+    "src"
   ],
   "exports": {
     ".": {

package/src/arrays.d.ts

@@ -0,0 +1,34 @@
+export interface Arrayable<TValue> {
+    toArray(): TValue[];
+}
+
+export interface ArrayAccess<TValue> {
+    offsetExists(offset: number | string): boolean;
+    offsetGet(offset: number | string): TValue | undefined;
+    offsetSet(offset: number | string, value: TValue): void;
+    offsetUnset(offset: number | string): void;
+}
+
+export type ArrayInnerValue<X> = X extends ReadonlyArray<infer U> ? U : never;
+
+export type ArrayItems<T> = T[] | Array<T>;
+
+/**
+ * Helper type to check if an array is mutable (not readonly)
+ */
+type IsMutableArray<T> = T extends readonly unknown[]
+    ? T extends unknown[]
+        ? true
+        : false
+    : false;
+
+/**
+ * Helper type to add a value to an array type.
+ * Excludes readonly arrays as they cannot be mutated.
+ */
+export type AddToArray<T extends unknown[], V> =
+    IsMutableArray<T> extends true
+        ? T extends Array<infer U>
+            ? Array<U | V>
+            : never
+        : never;

package/src/collections.d.ts

@@ -0,0 +1,2 @@
+export type ProxyTarget = this;
+export type PropertyName = string | symbol;

package/src/data.d.ts

@@ -0,0 +1,19 @@
+export type DataItems<TValue, TKey extends PropertyKey = PropertyKey> =
+    | TValue[]
+    | Record<TKey, TValue>;
+
+export interface Countable {
+    count(): number;
+}
+
+export interface IteratorAggregate<TValue, TKey> {
+    getIterator(): IterableIterator<[TKey, TValue]>;
+}
+
+export interface Jsonable {
+    toJson(): string;
+}
+
+export interface JsonSerializable {
+    jsonSerialize(): unknown;
+}

package/src/index.d.ts

@@ -0,0 +1,10 @@
+export type * from "./arrays";
+export type * from "./collections";
+export type * from "./data";
+export type * from "./models";
+export type * from "./objects";
+export type * from "./pagination";
+export type * from "./path-type";
+export type * from "./responses";
+export type * from "./strings";
+export type * from "./utils";

package/src/models.d.ts

@@ -0,0 +1,43 @@
+export interface Model {
+    id?: string | number;
+    [key: string]: unknown;
+}
+
+export interface Timestamps {
+    created_at: string | null;
+    updated_at: string | null;
+}
+
+export interface SoftDeletes {
+    deleted_at: string | null;
+}
+
+export interface TimestampModel extends Model, Timestamps {}
+export interface SoftDeleteModel extends Model, SoftDeletes {}
+export interface AllTimestampsModel extends Model, Timestamps, SoftDeletes {}
+
+export type AsCount<T extends string> = `${T}_count`;
+export type AsMax<T extends string> = `${T}_max`;
+export type AsMin<T extends string> = `${T}_min`;
+export type AsSum<T extends string> = `${T}_sum`;
+export type AsAvg<T extends string> = `${T}_avg`;
+export type AsExists<T extends string> = `${T}_exists`;
+
+export type WithCount<Relations extends string> = {
+    [K in Relations as AsCount<K>]: number;
+};
+export type WithMax<Relations extends string> = {
+    [K in Relations as AsMax<K>]: number | null;
+};
+export type WithMin<Relations extends string> = {
+    [K in Relations as AsMin<K>]: number | null;
+};
+export type WithSum<Relations extends string> = {
+    [K in Relations as AsSum<K>]: number | null;
+};
+export type WithAvg<Relations extends string> = {
+    [K in Relations as AsAvg<K>]: number | null;
+};
+export type WithExists<Relations extends string> = {
+    [K in Relations as AsExists<K>]: boolean;
+};

package/src/objects.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Helper type to add a key-value pair to an object type
+ */
+export type AddToObject<
+    T extends Record<PropertyKey, unknown>,
+    K extends PropertyKey,
+    V,
+> = T & Record<K, V>;

package/src/pagination.d.ts

@@ -0,0 +1,43 @@
+export interface SimplePaginator<T> {
+    current_page: number;
+    data: T[];
+    first_page_url: string;
+    from: number;
+    next_page_url: string | null;
+    path: string;
+    per_page: number;
+    prev_page_url: string | null;
+    to: number;
+}
+
+export interface LengthAwarePaginator<T> {
+    current_page: number;
+    data: T[];
+    first_page_url: string;
+    from: number;
+    last_page: number;
+    last_page_url: string;
+    links: PaginatorLink[];
+    next_page_url: string | null;
+    path: string;
+    per_page: number;
+    prev_page_url: string | null;
+    to: number;
+    total: number;
+}
+
+export interface CursorPaginator<T> {
+    data: T[];
+    path: string;
+    per_page: number;
+    next_cursor: string | null;
+    next_page_url: string | null;
+    prev_cursor: string | null;
+    prev_page_url: string | null;
+}
+
+export interface PaginatorLink {
+    url: string | null;
+    label: string;
+    active: boolean;
+}

package/src/path-type.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A key used to access a path in an object or array.
+ */
+export type PathKey = number | string | null | undefined;
+
+/**
+ * A set of keys used to access a path in an object or array.
+ */
+export type PathKeys = number | string | null | undefined | Array<PathKey>;
+
+/**
+ * Unwraps a value or function that returns a value.
+ */
+export type UnwrapFn<T> = T extends (...args: unknown[]) => infer R ? R : T;
+
+/**
+ * Helper to get array element type
+ */
+type ArrayElement<T> = T extends readonly (infer U)[] ? U : never;
+
+/**
+ * Helper to check if a type is an array
+ */
+type IsArray<T> = T extends readonly unknown[] ? true : false;
+
+/**
+ * Helper to check if a type is a tuple with at least one element
+ */
+type IsTuple<T> = T extends readonly [unknown, ...unknown[]]
+    ? true
+    : T extends readonly []
+      ? true
+      : false;
+
+/**
+ * Helper to get element at specific index in tuple
+ * For unions of tuples, returns the union of elements at that index
+ */
+type TupleElement<
+    T extends readonly unknown[],
+    N extends number,
+> = T extends readonly unknown[]
+    ? N extends keyof T
+        ? T[N]
+        : ArrayElement<T>
+    : never;
+
+/**
+ * Gets the type of a value at a given path in an object or array.
+ * Supports dot notation (a.b.c) and array indexing (a.0.b).
+ */
+export type GetFieldType<
+    T,
+    P extends string | number,
+    TDefault = never,
+> = P extends keyof T
+    ? T[P]
+    : P extends `${infer First}.${infer Rest}`
+      ? First extends keyof T
+          ? GetFieldType<T[First], Rest, TDefault>
+          : First extends `${infer N extends number}`
+            ? IsArray<T> extends true
+                ? T extends readonly unknown[]
+                    ? GetFieldType<T[N], Rest, TDefault>
+                    : TDefault
+                : TDefault
+            : TDefault
+      : P extends `${infer N extends number}`
+        ? IsArray<T> extends true
+            ? T extends readonly unknown[]
+                ? T[N]
+                : TDefault
+            : TDefault
+        : TDefault;

package/src/responses.d.ts

@@ -0,0 +1,25 @@
+import type { PaginatorLink } from "./pagination";
+
+export interface JsonResourceMeta {
+    current_page: number;
+    from: number;
+    last_page: number;
+    links: PaginatorLink[];
+    path: string;
+    per_page: number;
+    to: number;
+    total: number;
+}
+
+export interface JsonResourceLinks {
+    first: string | null;
+    last: string | null;
+    prev: string | null;
+    next: string | null;
+}
+
+export interface JsonResource<T> {
+    data: T[];
+    meta: JsonResourceMeta;
+    links: JsonResourceLinks;
+}

package/src/strings.d.ts

@@ -0,0 +1,3 @@
+export interface CanBeEscapedWhenCastToString {
+    escapeWhenCastToString(escape: boolean): this;
+}