@nmnmcc/ability 0.3.0 → 1.0.1

package/dist/Resource.d.ts

@@ -1,19 +1,7 @@
 import * as Schema from "effect/Schema";
 declare namespace Resource_d_exports {
-  export { Action, Any, Class, Data, Descriptor, FieldRef, Kind, Options, PathSegment, Resource, Struct, TypeId, Value, descriptor, isResource, make };
+  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 };
 }
-/**
- * @stability stable
- * @category type IDs
- * @since 0.3.0
- */
-export declare const TypeId: "~@nmnmcc/ability/Resource";
-/**
- * @stability stable
- * @category type IDs
- * @since 0.3.0
- */
-export type TypeId = typeof TypeId;
 /**
  * One part of a resource path. A string is a fixed part. A field reference
  * takes the part from a field of the value.
@@ -47,7 +35,18 @@ export interface Descriptor {
   readonly path: ReadonlyArray<PathSegment> | undefined;
   /** The paths of the data fields, with dots for nested fields. */
   readonly fieldPaths: ReadonlyArray<string>;
-  /** The Schema of the values, with the `_tag` field. */
+  /**
+   * 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;
 }
 /**
@@ -61,7 +60,7 @@ export interface Descriptor {
 export interface Resource<Kind extends string, Action extends string, Data extends object, Value extends {
   readonly _tag: Kind;
 }> {
-  readonly [TypeId]: Descriptor;
+  readonly descriptor: Descriptor;
   readonly "~Resource"?: {
     readonly Kind: Kind;
     readonly Action: Action;
@@ -125,8 +124,152 @@ export interface Options<Actions extends ReadonlyArray<string>, Fields extends S
    * 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<PathSegment>;
+  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}.
  *
@@ -149,16 +292,16 @@ export type Class<Self, Kind extends string, Actions extends ReadonlyArray<strin
  * import { Schema } from "effect"
  * import { Resource } from "@nmnmcc/ability"
  *
- * class Bot extends Resource.Class<Bot>()("Bot", {
+ * class Document extends Resource.Class<Document>()("Document", {
  *   actions: ["read", "update"],
  *   fields: {
  *     id: Schema.String,
- *     ownerUserId: Schema.NullOr(Schema.String),
+ *     teamId: Schema.NullOr(Schema.String),
  *   },
- *   path: (f) => ["user", f.ownerUserId, "bot", f.id],
+ *   path: (f) => ["team", f.teamId, "doc", f.id],
  * }) {}
  *
- * const bot = new Bot({ id: "b1", ownerUserId: "u1" })
+ * const document = new Document({ id: "d1", teamId: "t1" })
  * ```
  *
  * @stability stable
@@ -209,5 +352,13 @@ export declare const isResource: (u: unknown) => u is Any;
  * @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

@@ -1 +1 @@
-{"version":3,"file":"Resource.d.ts","names":[],"sources":["../src/Resource.ts"],"mappings":";;;;;;;;;qBA+Ba;;;;;;YAOD,gBAAgB;;;;;;;;;YAUhB,uBAAuB;;;;;;;;iBASlB,SAAS;WAChB;WACA,OAAO;;;;;;;;;iBAUA;WACP;WACA,SAAS;WACT,MAAM,cAAc;;WAEpB,YAAY;;WAEZ,QAAQ,OAAO;;;;;;;;;;iBAWR,SAChB,qBACA,uBACA,qBACA;WAAyB,MAAM;;YAErB,SAAS;WACV;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,cAAc;;;;;;;;;YAUT,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;;;;;;;;iBASb,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;;;;;;;;qBASd,aAAa,eAAe,KAAK;;;;;;;;qBASjC,aAAa,UAAU,QAAQ"}
+{"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"}