@nmnmcc/ability 0.2.0 → 1.0.0

package/dist/Resource.d.ts

@@ -0,0 +1,364 @@
+import * as Schema from "effect/Schema";
+declare namespace Resource_d_exports {
+  export { Action, Any, Class, Data, Descriptor, FieldDomain, FieldRef, Kind, Options, PathSegment, Resource, Struct, Value, anyDomain, descriptor, domainOf, fieldPaths, hasGetter, hasMatchingGetter, hasMatchingPath, hasNoValue, hasPath, hasValue, isPlainField, isResource, kindOf, make };
+}
+/**
+ * One part of a resource path. A string is a fixed part. A field reference
+ * takes the part from a field of the value.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export type PathSegment = string | FieldRef<string>;
+/**
+ * A reference to a top-level field of a resource, used in a path.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export interface FieldRef<Name extends string> {
+  readonly _tag: "Field";
+  readonly field: Name;
+}
+/**
+ * The runtime data of a resource.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Descriptor {
+  readonly kind: string;
+  readonly actions: ReadonlyArray<string>;
+  readonly path: ReadonlyArray<PathSegment> | undefined;
+  /** The paths of the data fields, with dots for nested fields. */
+  readonly fieldPaths: ReadonlyArray<string>;
+  /**
+   * The paths in {@link fieldPaths} of fields that hold more than one value,
+   * such as a record, a map or an array. The parts of such a field are not
+   * in `fieldPaths`, but a rule may name them.
+   */
+  readonly openPaths: ReadonlyArray<string>;
+  /**
+   * A struct Schema of the data of the values, with the `_tag` field. It is a
+   * struct also for a `Resource.Class`. The class Schema must not be read
+   * before the class is made, because Effect then binds the class Schema to
+   * the base class, and the values lose the getters of the class.
+   */
+  readonly schema: Schema.Top;
+}
+/**
+ * A resource. `Kind` is its name, `Action` is the union of its actions, `Data`
+ * is the type of its Schema fields, and `Value` is the type of its values.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Resource<Kind extends string, Action extends string, Data extends object, Value extends {
+  readonly _tag: Kind;
+}> {
+  readonly descriptor: Descriptor;
+  readonly "~Resource"?: {
+    readonly Kind: Kind;
+    readonly Action: Action;
+    readonly Data: Data;
+    readonly Value: Value;
+  };
+}
+/**
+ * Any resource.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export type Any = Resource<string, string, object, {
+  readonly _tag: string;
+}>;
+/**
+ * The kind name of a resource.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Kind<R> = R extends Resource<infer K, any, any, any> ? K : never;
+/**
+ * The actions of a resource.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Action<R> = R extends Resource<any, infer A, any, any> ? A : never;
+/**
+ * The type of the Schema fields of a resource, without `_tag`.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Data<R> = R extends Resource<any, any, infer D, any> ? D : never;
+/**
+ * The type of the values of a resource.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Value<R> = R extends Resource<any, any, any, infer V> ? V : never;
+/**
+ * The options of a resource.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Options<Actions extends ReadonlyArray<string>, Fields extends Schema.Struct.Fields> {
+  readonly actions: Actions;
+  readonly fields: Fields;
+  /**
+   * Gives the path of the resource. The function gets one reference for each
+   * top-level field.
+   */
+  readonly path?: (fields: { readonly [K in keyof Fields & string]: FieldRef<K>; }) => ReadonlyArray<string | FieldRef<keyof Fields & string>>;
+}
+/**
+ * Tests if a path names a getter of a class Schema, such as a getter of a
+ * `Schema.Class` or a `Principal.Class`, at its root or in a nested field. A
+ * condition reads such a field, and the types of a condition take it, so the
+ * check of a policy takes it too. It goes into the fields of a struct, the
+ * values of a record, the members of a union, `Schema.suspend`, and a class
+ * with an annotation or a check.
+ *
+ * @stability stable
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const hasGetter: (schema: unknown, path: string) => boolean;
+/**
+ * Tests if a Schema has a getter of a class at a path whose parts fit
+ * `parts`, as `hasGetter` does for one path. A part fits a name when `fits`
+ * says so, as a part with `*` fits many names. A part `**` stands for any
+ * number of parts, also none.
+ *
+ * @stability stable
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const hasMatchingGetter: (schema: unknown, parts: ReadonlyArray<string>, fits: (part: string, name: string) => boolean) => boolean;
+/**
+ * Gives the paths of all the fields of a Schema, with dots for nested fields.
+ * A nested struct gives its own path and the paths of its fields. Arrays are
+ * left out. It throws when a field name has a dot or is empty, because such a
+ * name would give two fields one path, or a path with an empty part.
+ *
+ * @stability stable
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const fieldPaths: (schema: Schema.Top) => ReadonlyArray<string>;
+/**
+ * Tests if a path names a plain scalar field of a Schema: a string, a number,
+ * a boolean, a literal, `null`, or an optional field or a union of these. Its
+ * only checks may be integer and finite checks: another check, such as
+ * `isGreaterThan(0)`, stops values that the search does not know about. On
+ * the way, each part must be a required field of a plain struct with no
+ * checks, with a name that is not a name of `Object.prototype`.
+ *
+ * `Policy.coverage` and `Condition.satisfiable` answer `All`, `None` or
+ * `Some` only when each field of the condition is such a field. Their model of
+ * the values of a field is exact for these Schemas. For other Schemas, such as
+ * classes, records, unions of structs or declarations, a value may have data
+ * that the Schema does not show, and the answer is `Unknown`.
+ *
+ * @stability stable
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const isPlainField: (schema: Schema.Top, path: string) => boolean;
+/**
+ * Tests if a path names a field of a Schema that holds a value with no named
+ * fields: a scalar, or a value such as a record or an array. It goes into
+ * records by their keys, and into recursive Schemas as far as the path goes.
+ * So it finds paths that {@link fieldPaths} does not list.
+ *
+ * @stability stable
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const hasPath: (schema: Schema.Top, path: string) => boolean;
+/**
+ * Tests if a Schema has a field whose path fits a pattern. `parts` are the
+ * parts of the pattern, split at the dots. A part `**` stands for any number
+ * of parts, also none. Another part fits a name when `fits` says so, as a
+ * part with `*` fits many names. For a record, the walk asks if the key
+ * Schema takes a key that fits the part. For a template literal key Schema,
+ * with parts that are literals and strings, the answer is exact. For another key Schema, the walk tries sample keys, so it may miss a
+ * key, and then the answer is `false`.
+ *
+ * @stability stable
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const hasMatchingPath: (schema: Schema.Top, parts: ReadonlyArray<string>, fits: (part: string, name: string) => boolean) => boolean;
+/**
+ * Tests if a Schema surely has a value: each required field, at each depth,
+ * has a type that has values, with no checks other than integer and finite
+ * checks on numbers. A check such as a minimum length may stop every value,
+ * and the library can not see that, so such a Schema gives `false`. So does a
+ * required field that holds the struct itself again.
+ *
+ * @stability stable
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const hasValue: (schema: Schema.Top) => boolean;
+/**
+ * Tests if a Schema has no value at all: a required field of it, at some
+ * depth, has no value, as `Schema.Never` has none. A required field that
+ * holds the struct itself again, with no way to stop, has no finite value
+ * either. Other checks, such as a minimum and a maximum that do not meet, are
+ * not seen, so a "no" does not prove that the Schema has a value.
+ *
+ * @stability stable
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const hasNoValue: (schema: Schema.Top) => boolean;
+/**
+ * The values that one field of a resource may hold, as a condition sees them.
+ * A missing field and `undefined` are `null`. The domain may be larger than
+ * the real set of values: Schema checks other than finite and integer checks
+ * are left out. A larger domain only makes a check say "no" more often.
+ *
+ * @stability stable
+ * @category models
+ * @since 1.0.0
+ */
+export interface FieldDomain {
+  /** The field may be `null` or missing. */
+  readonly null: boolean;
+  /** The field may hold a value with parts, or a value that is not a scalar. */
+  readonly object: boolean;
+  /** The field may hold `true` and `false`. */
+  readonly boolean: boolean;
+  /** The field may hold any string. */
+  readonly string: boolean;
+  /** The numbers that the field may hold. */
+  readonly number: "none" | "integer" | "finite" | "any";
+  /** Single values that the field may hold, other than the ones above. */
+  readonly literals: ReadonlyArray<string | number | boolean>;
+}
+/**
+ * The domain of a field with no Schema: any value.
+ *
+ * @stability stable
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const anyDomain: FieldDomain;
+/**
+ * Gives the domain of a field of a Schema, by its path with dots. A path that
+ * the Schema does not name gives `null`, as a condition reads such a field.
+ *
+ * @stability stable
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const domainOf: (schema: Schema.Top, path: string) => FieldDomain;
+/**
+ * The type of a class made by {@link Class}.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export type Class<Self, Kind extends string, Actions extends ReadonlyArray<string>, Fields extends Schema.Struct.Fields> = Schema.Class<Self, Schema.TaggedStruct<Kind, Fields>, {}> & Resource<Kind, Actions[number], Schema.Struct.Type<Fields>, Self & {
+  readonly _tag: Kind;
+}> & {
+  readonly kind: Kind;
+  readonly actions: Actions;
+};
+/**
+ * Makes a resource as a Schema class. Use it in the same way as
+ * `Schema.TaggedClass`.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Resource } from "@nmnmcc/ability"
+ *
+ * class Bot extends Resource.Class<Bot>()("Bot", {
+ *   actions: ["read", "update"],
+ *   fields: {
+ *     id: Schema.String,
+ *     ownerUserId: Schema.NullOr(Schema.String),
+ *   },
+ *   path: (f) => ["user", f.ownerUserId, "bot", f.id],
+ * }) {}
+ *
+ * const bot = new Bot({ id: "b1", ownerUserId: "u1" })
+ * ```
+ *
+ * @stability stable
+ * @category constructors
+ * @since 0.3.0
+ */
+export declare const Class: <Self = never>(identifier?: string) => <const Kind extends string, const Actions extends ReadonlyArray<string>, const Fields extends Schema.Struct.Fields>(kind: Kind, options: Options<Actions, Fields>) => [Self] extends [never] ? "Missing `Self` type: use Resource.Class<Self>()(...)" : Class<Self, Kind, Actions, Fields>;
+/**
+ * A resource made by {@link make}. Its values are plain objects.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Struct<Kind extends string, Actions extends ReadonlyArray<string>, Fields extends Schema.Struct.Fields> extends Resource<Kind, Actions[number], Schema.Struct.Type<Fields>, Schema.Struct.Type<Fields> & {
+  readonly _tag: Kind;
+}> {
+  readonly kind: Kind;
+  readonly actions: Actions;
+  readonly schema: Schema.TaggedStruct<Kind, Fields>;
+  /** Makes a value. It puts the `_tag` field on the value for you. */
+  readonly make: (input: Schema.Struct.Type<Fields>) => Schema.Struct.Type<Fields> & {
+    readonly _tag: Kind;
+  };
+}
+/**
+ * Makes a resource from plain fields. Its values are plain objects with a
+ * `_tag` field.
+ *
+ * @stability stable
+ * @category constructors
+ * @since 0.3.0
+ */
+export declare const make: <const Kind extends string, const Actions extends ReadonlyArray<string>, const Fields extends Schema.Struct.Fields>(kind: Kind, options: Options<Actions, Fields>) => Struct<Kind, Actions, Fields>;
+/**
+ * Tests if a value is a resource.
+ *
+ * @stability stable
+ * @category guards
+ * @since 0.3.0
+ */
+export declare const isResource: (u: unknown) => u is Any;
+/**
+ * Gets the runtime data of a resource.
+ *
+ * @stability stable
+ * @category getters
+ * @since 0.3.0
+ */
+export declare const descriptor: (resource: Any) => Descriptor;
+/**
+ * Gives the kind name of a resource value, from its `_tag` field.
+ *
+ * @stability stable
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const kindOf: (value: unknown) => string | undefined;
+export { Resource_d_exports };
+//# sourceMappingURL=Resource.d.ts.map

package/dist/Resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Resource.d.ts","names":[],"sources":["../src/Resource.ts"],"mappings":";;;;;;;;;;;;YAwCY,uBAAuB;;;;;;;;iBASlB,SAAS;WAChB;WACA,OAAO;;;;;;;;;iBAUA;WACP;WACA,SAAS;WACT,MAAM,cAAc;;WAEpB,YAAY;;;;;;WAMZ,WAAW;;;;;;;WAOX,QAAQ,OAAO;;;;;;;;;;iBAWR,SAChB,qBACA,uBACA,qBACA;WAAyB,MAAM;;WAEtB,YAAY;WACZ;aACC,MAAM;aACN,QAAQ;aACR,MAAM;aACN,OAAO;;;;;;;;;;YAWN,MAAM;WAA4C;;;;;;;;;YASlD,KAAK,KAAK,UAAU,eAAe,oBAAoB;;;;;;;;YASvD,OAAO,KAAK,UAAU,oBAAoB,eAAe;;;;;;;;YASzD,KAAK,KAAK,UAAU,yBAAyB,UAAU;;;;;;;;YASvD,MAAM,KAAK,UAAU,8BAA8B,KAAK;;;;;;;;iBASnD,QAChB,gBAAgB,uBAChB,eAAe,OAAO,OAAO;WAEpB,SAAS;WACT,QAAQ;;;;;WAKR,QAAQ,oBACN,WAAW,kBAAkB,SAAS,UAC3C,uBAAuB,eAAe;;;;;;;;;;;;;;qBAiEhC,YAAS,iBAAmB;;;;;;;;;;;qBAgC5B,oBAAiB,iBACd,OACR,uBAAqB,OACrB,cAAc;;;;;;;;;;;qBAuRT,aAAU,QAAY,OAAO,QAAM;;;;;;;;;;;;;;;;;;;qBA0EnC,eAAY,QAAY,OAAO,KAAG;;;;;;;;;;;qBAmClC,UAAO,QAAY,OAAO,KAAG;;;;;;;;;;;;;;qBAuF7B,kBAAe,QACnB,OAAO,KAAG,OACX,uBAAqB,OACrB,cAAc;;;;;;;;;;;;qBAkVT,WAAQ,QAAY,OAAO;;;;;;;;;;;;qBAiJ3B,aAAU,QAAY,OAAO;;;;;;;;;;;iBA0CzB;;WAEP;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA,UAAU;;;;;;;;;qBAyBP,WAAW;;;;;;;;;qBA0MX,WAAQ,QAAY,OAAO,KAAG,iBAAiB;;;;;;;;YAsIhD,MACX,MACA,qBACA,gBAAgB,uBAChB,eAAe,OAAO,OAAO,UAC1B,OAAO,MAAM,MAAM,OAAO,aAAa,MAAM,eAChD,SACC,MACA,iBACA,OAAO,OAAO,KAAK,SACnB;WAAkB,MAAM;;WAEf,MAAM;WACN,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA4BP,QAAQ,cACpB,+BAEM,2BACA,gBAAgB,6BAChB,eAAe,OAAO,OAAO,QAEnC,MAAM,MACN,SAAS,QAAQ,SAAS,aACrB,iFAEH,MAAM,MAAM,MAAM,SAAS;;;;;;;;iBAyBb,OAChB,qBACA,gBAAgB,uBAChB,eAAe,OAAO,OAAO,gBACpB,SACT,MACA,iBACA,OAAO,OAAO,KAAK,SACnB,OAAO,OAAO,KAAK;WAAqB,MAAM;;WAErC,MAAM;WACN,SAAS;WACT,QAAQ,OAAO,aAAa,MAAM;;WAElC,OACR,OAAO,OAAO,OAAO,KAAK,YACtB,OAAO,OAAO,KAAK;aAAqB,MAAM;;;;;;;;;;;qBAWvC,aACN,2BACA,gBAAgB,6BAChB,eAAe,OAAO,OAAO,QAEnC,MAAM,MACN,SAAS,QAAQ,SAAS,YACtB,OAAO,MAAM,SAAS;;;;;;;;qBA0Bd,aAAU,eAAiB,KAAK;;;;;;;;qBAUhC,aAAU,UAAc,QAAM;;;;;;;;qBAS9B,SAAM"}