pg-introspection 0.0.0

package/LICENSE.md

@@ -0,0 +1,45 @@
+# The MIT License (MIT)
+
+Copyright © `2022` Benjie Gillam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# PostgreSQL documentation
+
+This package contains excerpts from the PostgreSQL documentation; the following
+license applies to those excerpts:
+
+PostgreSQL is Copyright © 1996–2022 by the PostgreSQL Global Development Group.
+
+Postgres95 is Copyright © 1994–5 by the Regents of the University of California.
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement is
+hereby granted, provided that the above copyright notice and this paragraph and
+the following two paragraphs appear in all copies.
+
+IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
+DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST
+PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
+THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
+BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN “AS-IS” BASIS, AND
+THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
+UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

package/README.md

@@ -0,0 +1,105 @@
+# pg-introspection
+
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/benjie?color=ff69b4&label=github%20sponsors)](https://github.com/sponsors/benjie)
+[![Patreon sponsor button](https://img.shields.io/badge/sponsor-via%20Patreon-orange.svg)](https://patreon.com/benjie)
+[![Discord chat room](https://img.shields.io/discord/489127045289476126.svg)](http://discord.gg/graphile)
+[![Follow](https://img.shields.io/badge/twitter-@GraphileHQ-blue.svg)](https://twitter.com/GraphileHQ)
+
+A strongly-typed PostgreSQL introspection library for PostgreSQL built
+automatically from the
+[PostgreSQL system catalog documentation](https://www.postgresql.org/docs/current/catalogs.html),
+with the TypeScript documentation for each attribute/type also pulled from the
+PostgreSQL documentation for easy reference directly in your editor.
+
+<!-- SPONSORS_BEGIN -->
+
+## Crowd-funded open-source software
+
+To help us develop this software sustainably under the MIT license, we ask all
+individuals and businesses that use it to help support its ongoing maintenance
+and development via sponsorship.
+
+### [Click here to find out more about sponsors and sponsorship.](https://www.graphile.org/sponsor/)
+
+And please give some love to our featured sponsors 🤩:
+
+<table><tr>
+<td align="center"><a href="https://surge.io/"><img src="https://graphile.org/images/sponsors/surge.png" width="90" height="90" alt="Surge" /><br />Surge</a> *</td>
+<td align="center"><a href="https://storyscript.com/?utm_source=postgraphile"><img src="https://graphile.org/images/sponsors/storyscript.png" width="90" height="90" alt="Story.ai" /><br />Story.ai</a> *</td>
+<td align="center"><a href="http://chads.website"><img src="https://graphile.org/images/sponsors/chadf.png" width="90" height="90" alt="Chad Furman" /><br />Chad Furman</a> *</td>
+<td align="center"><a href="https://www.fanatics.com/"><img src="https://graphile.org/images/sponsors/fanatics.png" width="90" height="90" alt="Fanatics" /><br />Fanatics</a> *</td>
+</tr><tr>
+<td align="center"><a href="https://qwick.com/"><img src="https://graphile.org/images/sponsors/qwick.png" width="90" height="90" alt="Qwick" /><br />Qwick</a> *</td>
+<td align="center"><a href="https://www.the-guild.dev/"><img src="https://graphile.org/images/sponsors/theguild.png" width="90" height="90" alt="The Guild" /><br />The Guild</a> *</td>
+<td align="center"><a href="https://dovetailapp.com/"><img src="https://graphile.org/images/sponsors/dovetail.png" width="90" height="90" alt="Dovetail" /><br />Dovetail</a> *</td>
+<td align="center"><a href="https://www.enzuzo.com/"><img src="https://graphile.org/images/sponsors/enzuzo.png" width="90" height="90" alt="Enzuzo" /><br />Enzuzo</a> *</td>
+</tr><tr>
+<td align="center"><a href="https://stellate.co/"><img src="https://graphile.org/images/sponsors/Stellate.png" width="90" height="90" alt="Stellate" /><br />Stellate</a> *</td>
+</tr></table>
+
+<em>\* Sponsors the entire Graphile suite</em>
+
+<!-- SPONSORS_END -->
+
+## Usage
+
+Issue the `makeIntrospectionQuery()` SQL query to your database, then feed the
+first row's `introspection` field into `parseIntrospectionResults()` to get your
+strongly typed introspection results.
+
+Example usage with `pg` module:
+
+```js
+import {
+  makeIntrospectionQuery,
+  parseIntrospectionResults,
+} from "pg-introspection";
+import { Pool } from "pg";
+
+const pool = new Pool({
+  connectionString: "postgres://localhost:5432/my_database",
+});
+
+async function main() {
+  const sql = makeIntrospectionQuery();
+  const { rows } = await pool.query(sql);
+  const introspection = parseIntrospectionResults(row[0].introspection);
+
+  console.log(
+    `The ${introspection.database.datname} DBA is ${
+      introspection.database.getDba()?.rolname ?? "-"
+    }`,
+  );
+}
+
+main();
+```
+
+## Accessors
+
+Into the introspection results we mix "accessor" functions to make following
+relationships easier. Note that these functions are typically evaluated lazily -
+the first time you call them they may need to do an expensive lookup (e.g.
+finding the relevant record from the list of records) but they cache the result
+so that the next call will be near-instant.
+
+Examples:
+
+```js
+const myTable = introspection.classes.find((rel) => rel.relname === "my_table");
+const myTableAttributes = myTable.getAttributes();
+const myColumn = myTable.getAttribute({ name: "my_column" });
+const myColumnDescription = myColumn.getDescription();
+```
+
+You can use the TypeScript autocompletion to see what accessors are available,
+or look in the `index.ts` file.
+
+## Naming
+
+Using the PostgreSQL column names is _by design_, even though some are hard to
+read if you're not familiar with the system catalog.
+
+We use `_id` rather than `oid` because older versions of PostgreSQL did not
+explicitly list the `oid` columns when you `select * from` so we explicitly list
+them among the selection set.

package/dist/acl.d.ts

@@ -0,0 +1,151 @@
+import type { Introspection, PgClass, PgRoles } from "./introspection.js";
+/**
+ * A fake 'pg_roles' record representing the 'public' meta-role.
+ */
+export declare const PUBLIC_ROLE: PgRoles;
+/**
+ * Represents a single ACL entry in an ACL string, such as
+ * `foo=arwdDxt/bar`
+ */
+export interface AclObject {
+    /** Who are these permissions granted to? */
+    role: string;
+    /** Who granted these permissions? */
+    granter: string;
+    /** r */
+    select?: boolean;
+    /** r* */
+    selectGrant?: boolean;
+    /** w */
+    update?: boolean;
+    /** w* */
+    updateGrant?: boolean;
+    /** a */
+    insert?: boolean;
+    /** a* */
+    insertGrant?: boolean;
+    /** d */
+    delete?: boolean;
+    /** d* */
+    deleteGrant?: boolean;
+    /** D */
+    truncate?: boolean;
+    /** D* */
+    truncateGrant?: boolean;
+    /** x */
+    references?: boolean;
+    /** x* */
+    referencesGrant?: boolean;
+    /** t */
+    trigger?: boolean;
+    /** t* */
+    triggerGrant?: boolean;
+    /** X */
+    execute?: boolean;
+    /** X* */
+    executeGrant?: boolean;
+    /** U */
+    usage?: boolean;
+    /** U* */
+    usageGrant?: boolean;
+    /** C */
+    create?: boolean;
+    /** C* */
+    createGrant?: boolean;
+    /** c */
+    connect?: boolean;
+    /** c* */
+    connectGrant?: boolean;
+    /** T */
+    temporary?: boolean;
+    /** T* */
+    temporaryGrant?: boolean;
+}
+export declare type ResolvedPermissions = Omit<AclObject, "role" | "granter">;
+/**
+ * Accepts an ACL string such as `foo=arwdDxt/bar` and converts it into
+ * a parsed AclObject.
+ */
+export declare function parseAcl(aclString: string): AclObject;
+/**
+ * Takes an `AclObject` and converts it back into a Postgres ACL string such as
+ * `foo=arwdDxt/bar`
+ */
+export declare function serializeAcl(acl: AclObject): string;
+export declare const emptyAclObject: AclObject;
+export declare const OBJECT_COLUMN = "OBJECT_COLUMN";
+export declare const OBJECT_TABLE = "OBJECT_TABLE";
+export declare const OBJECT_SEQUENCE = "OBJECT_SEQUENCE";
+export declare const OBJECT_DATABASE = "OBJECT_DATABASE";
+export declare const OBJECT_FUNCTION = "OBJECT_FUNCTION";
+export declare const OBJECT_LANGUAGE = "OBJECT_LANGUAGE";
+export declare const OBJECT_LARGEOBJECT = "OBJECT_LARGEOBJECT";
+export declare const OBJECT_SCHEMA = "OBJECT_SCHEMA";
+export declare const OBJECT_TABLESPACE = "OBJECT_TABLESPACE";
+export declare const OBJECT_FDW = "OBJECT_FDW";
+export declare const OBJECT_FOREIGN_SERVER = "OBJECT_FOREIGN_SERVER";
+export declare const OBJECT_DOMAIN = "OBJECT_DOMAIN";
+export declare const OBJECT_TYPE = "OBJECT_TYPE";
+export declare type AclDefaultObjectType = typeof OBJECT_COLUMN | typeof OBJECT_TABLE | typeof OBJECT_SEQUENCE | typeof OBJECT_DATABASE | typeof OBJECT_FUNCTION | typeof OBJECT_LANGUAGE | typeof OBJECT_LARGEOBJECT | typeof OBJECT_SCHEMA | typeof OBJECT_TABLESPACE | typeof OBJECT_FDW | typeof OBJECT_FOREIGN_SERVER | typeof OBJECT_DOMAIN | typeof OBJECT_TYPE;
+/**
+ * Returns a list of AclObject by parsing the given input ACL strings. If no
+ * ACL strings are present then it will return the default (implied) ACL for
+ * the given `type` of entity owned by `ownerId`.
+ *
+ * See:
+ *
+ * https://github.com/postgres/postgres/blob/14aec03502302eff6c67981d8fd121175c436ce9/src/backend/utils/adt/acl.c#L748-L854
+ *
+ * and:
+ *
+ * https://github.com/postgres/postgres/blob/fb3b098fe88441f9531a5169008ea17eac01301f/src/include/utils/acl.h#L153-L167
+ */
+export declare function parseAcls(introspection: Introspection, inAcls: readonly string[] | null, ownerId: string, type: AclDefaultObjectType): AclObject[];
+export declare const Permission: {
+    readonly select: "select";
+    readonly selectGrant: "selectGrant";
+    readonly update: "update";
+    readonly updateGrant: "updateGrant";
+    readonly insert: "insert";
+    readonly insertGrant: "insertGrant";
+    readonly delete: "delete";
+    readonly deleteGrant: "deleteGrant";
+    readonly truncate: "truncate";
+    readonly truncateGrant: "truncateGrant";
+    readonly references: "references";
+    readonly referencesGrant: "referencesGrant";
+    readonly trigger: "trigger";
+    readonly triggerGrant: "triggerGrant";
+    readonly execute: "execute";
+    readonly executeGrant: "executeGrant";
+    readonly usage: "usage";
+    readonly usageGrant: "usageGrant";
+    readonly create: "create";
+    readonly createGrant: "createGrant";
+    readonly connect: "connect";
+    readonly connectGrant: "connectGrant";
+    readonly temporary: "temporary";
+    readonly temporaryGrant: "temporaryGrant";
+};
+export declare function aclsForTable(introspection: Introspection, table: PgClass): AclObject[];
+/**
+ * Returns all the roles role has been granted (including PUBLIC),
+ * respecting `NOINHERIT`
+ */
+export declare function expandRoles(introspection: Introspection, roles: PgRoles[], includeNoInherit?: boolean): PgRoles[];
+/**
+ * Returns true if ACL was applied to this role, or a role that this role
+ * inherits from (including public).
+ *
+ * i.e. does this ACL grant privileges to this role (directly or indirectly)?
+ *
+ * In Venn diagram terms, it asks if the 'role' is contained within (or equal to)
+ * the acl.role.
+ */
+export declare function aclContainsRole(introspection: Introspection, acl: AclObject, role: PgRoles, includeNoInherit?: boolean): boolean;
+/**
+ * Filters the ACL objects to only those that apply to `role`, then calculates
+ * the `OR` of all the permissions to see what permissions the role has.
+ */
+export declare function resolvePermissions(introspection: Introspection, acls: AclObject[], role: PgRoles, includeNoInherit?: boolean): ResolvedPermissions;
+//# sourceMappingURL=acl.d.ts.map

package/dist/acl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl.d.ts","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"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"}